Skip to main content
Creates a new Annotation for the specified indicator and returns the created object with its assigned id.

​
Path parameters

​
indicator_id
string
required
The indicator’s unique identifier. Must be a valid MongoDB ObjectId (24-character hex string).

​
Request body

​
type
string
required
Axis the annotation is drawn on.
  • xaxis — a vertical reference line at an x-axis position (use a datetime value)
  • yaxis — a horizontal reference line at a y-axis position (use a numeric value)
​
value
string | number
required
Position of the annotation line.
  • For xaxis: an ISO 8601 datetime string (e.g., "2024-06-01T00:00:00Z").
  • For yaxis: a numeric value (e.g., 1500.0).
String values containing T are parsed as datetimes; other strings are parsed as floats.
​
label
string
required
Human-readable label displayed next to the annotation line on the chart.
​
color
string
default:"#000000"
CSS hex color for the annotation line (e.g., "#FF5733").
​
stroke_dasharray
integer
default:"0"
Dash pattern for the annotation line. 0 renders a solid line. Positive integers set the dash length in pixels.
​
opacity
number
default:"1.0"
Opacity of the annotation line, from 0.0 (transparent) to 1.0 (fully opaque).

​
Response

Returns the created Annotation object, including the server-assigned id and indicator_id.
​
id
string
Unique identifier assigned to the new annotation.
​
indicator_id
string
required
The ObjectId of the indicator this annotation belongs to.
​
type
string
required
xaxis or yaxis, as provided.
​
value
string | number
required
Parsed annotation position. Datetime strings are normalized to ISO 8601.
​
label
string
required
Annotation label.
​
color
string
required
Hex color of the annotation line.
​
stroke_dasharray
integer
required
Dash length in pixels. 0 = solid.
​
opacity
number
required
Line opacity between 0.0 and 1.0.

​
Error responses

StatusDescription
400 Bad Requestindicator_id is not a valid ObjectId, or value cannot be parsed.

​
Examples

curl -X POST \
  "https://api.example.com/indicators/64b1f2c3d4e5f6a7b8c9d0e1/annotations" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "xaxis",
    "value": "2020-03-11T00:00:00Z",
    "label": "COVID-19 declared pandemic",
    "color": "#E74C3C",
    "stroke_dasharray": 4,
    "opacity": 0.8
  }'

import httpx

client = httpx.AsyncClient(base_url="https://api.example.com")
response = await client.post(
    "/indicators/64b1f2c3d4e5f6a7b8c9d0e1/annotations",
    json={
        "type": "xaxis",
        "value": "2020-03-11T00:00:00Z",
        "label": "COVID-19 declared pandemic",
        "color": "#E74C3C",
        "stroke_dasharray": 4,
        "opacity": 0.8,
    },
)
response.raise_for_status()
annotation = response.json()
print(annotation["id"])  # e.g. "64c2f3a1b5e6d7f8e9a0b1c2"

​
Example response

200
{
  "id": "64c2f3a1b5e6d7f8e9a0b1c2",
  "indicator_id": "64b1f2c3d4e5f6a7b8c9d0e1",
  "type": "xaxis",
  "value": "2020-03-11T00:00:00",
  "label": "COVID-19 declared pandemic",
  "color": "#E74C3C",
  "stroke_dasharray": 4,
  "opacity": 0.8
}

Build docs developers (and LLMs) love

Get started for freeTalk to us