> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sacra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create or retrieve a chart embed
> Creates a new chart (or retrieves an existing one) from one or more datasets and returns embeddable HTML. If a chart with the same name, description, and creator already exists, returns the existing embed with a 200. Otherwise creates a new chart and returns 201.
## OpenAPI
````yaml PUT /api/v1/embed/charts/
openapi: 3.0.3
info:
title: Sacra API
version: 1.0.0
description: >-
The Sacra API currently supports querying News, Documents, Companies and
Categories that enable you to use Sacra research within your own
application.
## **Getting started guide**
To start using the APIs, you need to:
- Only available to **Platforms** and **Funds** tier members. (See
[here](https://sacra.com/pricing/))
- You must use a valid API Key to send requests to the API endpoints. You
can generate your API key in the Api Keys section of your [Organization
Settings](https://sacra.com/orgs/settings/general/).
- The API returns request responses in JSON format. When an API request
returns an error, it is sent in the JSON response as an error key.
## Authentication
The Sacra API uses Tokens for authentication.
You can generate a Sacra API Key/Token in the Api Keys section of your
[Organization Settings](https://sacra.com/orgs/settings/general/).
You must include an API Key/Token in each request to the Sacra API with the
**Authorization** request header.
### Authentication error response
If a Token is missing, malformed, or invalid, you will receive an HTTP 401
Unauthorized response code.
### **Need some help?**
In case you have questions, we will eventually provide tutorials and a FAQ
page. But for now you can check out the
[#developers](https://discord.gg/mTswyV8gg3) channel in our community
[Discord](https://discord.gg/mTswyV8gg3), there’s a good chance our
community has an answer for you.
## Authorization
| **Key** | **Value** |
| --- | --- |
| Authorization | Token {{API_KEY}} |
servers:
- url: https://sacra.com
description: Production
security: []
tags:
- name: Companies
- name: Categories
- name: Events
- name: News
- name: Documents
- name: Filings
- name: Embeds
- name: Metrics
- name: Funding (Legacy)
paths:
/api/v1/embed/charts/:
put:
tags:
- Embeds
summary: Create or retrieve a chart embed
description: >-
Creates a new chart (or retrieves an existing one) from one or more
datasets and returns embeddable HTML. If a chart with the same name,
description, and creator already exists, returns the existing embed with
a 200. Otherwise creates a new chart and returns 201.
operationId: embed_charts_update
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChartsEmbedRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ChartsEmbedRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ChartsEmbedRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChartEmbedSuccessResponse'
examples:
ExistingChart:
value:
status: success
data:
embed_html: >
description: Existing chart found. Returns its embed HTML.
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ChartEmbedCreatedResponse'
examples:
NewChart:
value:
status: success
data:
embed_html: >
description: New chart created. Returns its embed HTML.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ChartEmbedErrorResponse'
examples:
ParseError:
value:
status: failed
message: Could not parse the request body.
BadDatasetId:
value:
status: failed
message: dataset_id is malformed
description: Malformed request body or invalid dataset_id.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ChartEmbedNotFoundResponse'
examples:
DatasetNotFound:
value:
status: failed
message: Dataset not found
description: A referenced dataset was not found.
security:
- tokenAuth: []
components:
schemas:
ChartsEmbedRequest:
type: object
properties:
name:
type: string
description: Chart title. Defaults to a sorted join of dataset names.
description:
type: string
description: Chart description. Defaults to 'API Generated Chart'.
data:
type: array
items:
$ref: '#/components/schemas/ChartDataItem'
required:
- data
ChartEmbedSuccessResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/ChartEmbedData'
required:
- data
- status
ChartEmbedCreatedResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/ChartEmbedCreatedData'
required:
- data
- status
ChartEmbedErrorResponse:
type: object
properties:
status:
type: string
message:
type: string
required:
- message
- status
ChartEmbedNotFoundResponse:
type: object
properties:
status:
type: string
message:
type: string
required:
- message
- status
ChartDataItem:
type: object
properties:
dataset_id:
type: integer
description: ID of the dataset to chart.
view_type:
allOf:
- $ref: '#/components/schemas/ViewTypeEnum'
description: |-
Rendering style. Defaults to `column`.
* `column` - column
* `line` - line
* `area` - area
* `bar` - bar
color:
type: string
description: Hex color for the series (e.g. `#FF5733`).
annotated_points:
type: array
items:
type: object
additionalProperties: {}
description: Data points to annotate on the chart.
show_data_labels:
type: boolean
default: true
description: 'Show value labels on data points. Default: true.'
required:
- dataset_id
ChartEmbedData:
type: object
properties:
embed_html:
type: string
required:
- embed_html
ChartEmbedCreatedData:
type: object
properties:
embed_html:
type: string
required:
- embed_html
ViewTypeEnum:
enum:
- column
- line
- area
- bar
type: string
description: |-
* `column` - column
* `line` - line
* `area` - area
* `bar` - bar
securitySchemes:
tokenAuth:
type: apiKey
in: header
name: Authorization
description: Token-based authentication with required prefix "Token"
````