Annotations API

The CJA Annotations APIs allow you to retrieve, update, or create annotations programmatically through Adobe Developer. These APIs use the same data and methods that Adobe uses inside the product UI.

Adobe may add optional request and response members (name/value pairs) to existing API objects at any time and without notice or changes in versioning. Adobe recommends that you refer to the API documentation of any third-party tool you integrate with our APIs so that such additions are ignored in processing if not understood. If implemented properly, such additions are non-breaking changes for your implementation. Adobe will not remove parameters or add required parameters without first providing standard notification through release notes.

Retrieve multiple annotations

Retrieve a list of annotations that the user can access. See Annotation parameters for query strings that you can attach to this API call.

GET https://cja.adobe.io/annotations

For example, get a response of all annotations shared with the user.

Request

Response

curl -X GET "https://cja.adobe.io/annotations?includeType=shared" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-gw-ims-org-id: {IMSORG}" \
    -H "Authorization: Bearer {ACCESSTOKEN}"
Copied to your clipboard
curl -X GET "https://cja.adobe.io/annotations?includeType=shared" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-gw-ims-org-id: {IMSORG}" \
    -H "Authorization: Bearer {ACCESSTOKEN}"

{
    "content": [
        {
            "id": "62437d"
        }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "numberOfElements": 1,
    "number": 0,
    "firstPage": true,
    "lastPage": true,
    "sort": null,
    "size": 10
}
Copied to your clipboard
{
    "content": [
        {
            "id": "62437d"
        }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "numberOfElements": 1,
    "number": 0,
    "firstPage": true,
    "lastPage": true,
    "sort": null,
    "size": 10
}

Retrieve a single annotation

You can retrieve details around a single annotation if you know the annotation ID. You can find the annotation ID by using the multiple annotations endpoint. See Annotation parameters for query strings that you can attach to this API call.

GET https://cja.adobe.io/annotations/{ID}

For example, find details around the annotation with an ID of 62437d, including the name, description, date range, and color:

Request

Response

curl -X GET "https://cja.adobe.io/annotations/62437d?expansion=name,description,dateRange,color" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-gw-ims-org-id: {IMSORG}" \
    -H "Authorization: Bearer {ACCESSTOKEN}"
Copied to your clipboard
curl -X GET "https://cja.adobe.io/annotations/62437d?expansion=name,description,dateRange,color" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-gw-ims-org-id: {IMSORG}" \
    -H "Authorization: Bearer {ACCESSTOKEN}"

{
    "id": "62437d",
    "name": "Example annotation",
    "description": "This is an example annotation description.",
    "dateRange": "YYYY-03-29T00:00:00/YYYY-03-29T23:59:59",
    "color": "STANDARD6"
}
Copied to your clipboard
{
    "id": "62437d",
    "name": "Example annotation",
    "description": "This is an example annotation description.",
    "dateRange": "YYYY-03-29T00:00:00/YYYY-03-29T23:59:59",
    "color": "STANDARD6"
}

Create an annotation

You can create annotations using POST API calls. The following fields are required within a JSON body attached to the API call:

name: The name of the annotation.
dataId: The data view ID for the annotation.
dateRange: The date range of the annotation. Use two date ranges separated by a forward slash (/) in ISO 8601 format, based on the report suite's time zone.
color: The annotation's color. Supported values include STANDARD1 through STANDARD9, representing each of the available colors in the UI.

Annotation colors

See Annotation definition data structure for a full reference of available fields.

POST https://cja.adobe.io/annotations

For example, create a basic annotation with the minimum required fields. The API responds with the automatically generated annotation ID.

Request

Response

curl -X POST 'https://cja.adobe.io/annotations' \
    -H 'x-api-key: {CLIENTID}' \
    -H 'x-gw-ims-org-id: {IMSORG}' \
    -H 'Authorization: Bearer {ACCESSTOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{"name": "Example annotation",
        "rsid": "examplersid",
        "dateRange": "YYYY-02-14T00:00:00/YYYY-02-14T23:59:59",
        "color": "STANDARD1"}'
Copied to your clipboard
curl -X POST 'https://cja.adobe.io/annotations' \
    -H 'x-api-key: {CLIENTID}' \
    -H 'x-gw-ims-org-id: {IMSORG}' \
    -H 'Authorization: Bearer {ACCESSTOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{"name": "Example annotation",
        "rsid": "examplersid",
        "dateRange": "YYYY-02-14T00:00:00/YYYY-02-14T23:59:59",
        "color": "STANDARD1"}'

{
    "id": "62439328"
}
Copied to your clipboard
{
    "id": "62439328"
}

Delete an annotation

When you delete an annotation, it is hidden from all users in all menus. It is also hidden from API calls to the multiple annotations endpoint. You can still retrieve details on a deleted annotation if you have the annotation ID.

DELETE https://cja.adobe.io/annotations/{ID}

For example, delete an annotation with the ID of 62437d:

Request

Response

curl -X DELETE "https://cja.adobe.io/annotations/62437d" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-gw-ims-org-id: {IMSORG}" \
    -H "Authorization: Bearer {ACCESSTOKEN}"
Copied to your clipboard
curl -X DELETE "https://cja.adobe.io/annotations/62437d" \
    -H "x-api-key: {CLIENTID}" \
    -H "x-gw-ims-org-id: {IMSORG}" \
    -H "Authorization: Bearer {ACCESSTOKEN}"

{
  "result": "success"
}
Copied to your clipboard
{
  "result": "success"
}

Update an annotation

You can edit annotations using PUT API calls. It supports partial updates, meaning that instead of sending an entire annotation JSON object, you can only send the fields that you want to update. This API call requires a JSON body, which determines the parts of an annotation that you want to update.

PUT https://cja.adobe.io/annotations/{ID}

See Annotation definition data structure for a full reference of available fields.

For example, only update the name of the annotation with an ID of 62437d:

Request

Response

curl -X PUT "https://cja.adobe.io/annotations/62437d" \
    -H 'x-api-key: {CLIENTID}' \
    -H 'x-gw-ims-org-id: {IMSORG}' \
    -H 'Authorization: Bearer {ACCESSTOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Different annotation name"}'
Copied to your clipboard
curl -X PUT "https://cja.adobe.io/annotations/62437d" \
    -H 'x-api-key: {CLIENTID}' \
    -H 'x-gw-ims-org-id: {IMSORG}' \
    -H 'Authorization: Bearer {ACCESSTOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Different annotation name"}'

{
    "id": "62437d"
}
Copied to your clipboard
{
    "id": "62437d"
}

API status codes

For a description of API status codes and tips for troubleshooting, see the Platform FAQ and troubleshooting guide.

Endpoint guides

Parameters

Last updated 11/7/2024

Was this helpful?

Yes

Annotations API

Retrieve multiple annotations.css-83mclq{margin-left:var(--spectrum-global-dimension-size-100);}

Retrieve a single annotation

Create an annotation

Delete an annotation

Update an annotation

API status codes

Retrieve multiple annotations