Edit in GitHubLog an issue

Annotations API

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

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.

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

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:

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

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.

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

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:

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

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:

Copied to your clipboard
1curl -X PUT "https://cja.adobe.io/annotations/62437d" \
2 -H 'x-api-key: {CLIENTID}' \
3 -H 'x-gw-ims-org-id: {IMSORG}' \
4 -H 'Authorization: Bearer {ACCESSTOKEN}' \
5 -H 'Content-Type: application/json' \
6 -d '{"name":"Different annotation name"}'
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.