Annotations
{
id: string
document_id: string
user_id: string // The ID of the user that created the annotation
user_name: string // The display name of the user that created the annotation
ctx_and_id: string // A combination of context and id. Used for indexing the database
context: string
inreplyto: string
type: string
subject: string // Similar to 'type', a holdover from XFDF
page: number
icon: string
contents: string
coords: [
[
[
number
]
]
] // Ex: [[[256.51, 300.5], [459.79, 300.5], [256.51, 311.26], [459.79, 311.26]], [[35.99, 286.5], [264.27, 286.5], [35.99, 297.26], [264.27, 297.26]]]
rect: [
[
number
]
] // Ex: [[35.99, 286.5], [459.79, 311.26]]
color: string
font: string
text-align: string
opacity: number
inklist: {
gestures: [
[
{
x: number
y: number
width: number
opacity: number
}
]
]
} // Ex: [[{x: 498.34, y: 619.4}, {x: 498.34, y: 619.4}], [{x: 504.4, y: 620.07}, {x: 504.4, y: 620.07}, {x: 504.4, y: 620.07}]]
width: number
deleted: boolean // If this annotation has been soft-deleted. Soft-deleted annotations should only be returned if the current user is the creator of the annotation
deleted_at: string // When the annotation was deleted. Only present for deleted annotations. ISO format - Example: '2018-02-06T20:59:31.528Z'
deleted_by: string // The name of the user that deleted this annotation. Only present for deleted annotations
deleted_by_id: string // The ID of the user that deleted this annotation. Only present for deleted annotations
delete_acknowledged: string // When the creator of this annotation acknowledged its deletion. Annotations with delete_acknowledged true should never be returned to the client. ISO format - Example: '2018-02-06T20:59:31.528Z'
@version: string // The version of the API that was used to create this annotation
created_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
modified_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
}
- Get all Annotations for a Document
- Get an Annotation
- Create or Update an Annotation
- Delete an Annotation
Intro
Annotations and Comments are both represented as Annotations, differentiated
by the type
field. There are 6 different types of Annotations, as well as
Comments. Please see the Annotation Types page for information
on which fields are required for which annotation types, as well as descriptions
of the different types of annotations.
All Annotation endpoints require a Session ID.
See the API versioning page for an explanation of the version numbers in these endpoints.
Get all Annotations for a Document
GET /2018-04-06/sessions/{session_id}/annotations
DEPRECATED: GET /2018-03-07/sessions/{session_id}/annotations - does not return deleted annotations
Returns all Annotations that match the Document ID and context
specified in the session. If an annotation has been
deleted, and it was created by the current user, and
it has not been marked as delete-acknowledged
, it will be returned. Otherwise,
deleted annotations will be excluded.
Parameters
Query:
session_id: string
Responses
200
Returns an array of Annotation Objects
{
"data": [
Annotation Object
]
}
Example Call
GET http://canvadocs.docker/1/sessions/eyJhb.../annotations
200 OK
{
"data": [
{
"color": "#C31FA8",
"user_name": "Standard User",
"icon": "Comment",
"created_at": "2018-04-11T21:52:13.399Z",
"type": "text",
"document_id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"rect": [[527.66, 715.05], [536.99, 728.39]],
"ctx_and_id": "canvadocs_admin|1836e167-40df-43f6-91ed-d2ced0588914",
"user_id": "standard_user",
"context": "canvadocs_admin",
"@version": "1",
"page": 0,
"id": "1836e167-40df-43f6-91ed-d2ced0588914",
"modified_at": "2018-04-11T21:52:13.399Z",
"contents": "hello"
},
...
]
}
Get an Annotation
GET /2018-03-07/sessions/{session_id}/annotations/{annotation_id}
Returns a single annotation. Used primarily for automated testing, rather than by any of the clients.
Parameters
Query:
session_id: string
annotation_id: string
Responses
200
Returns an Annotation Object
Example Call
GET http://canvadocs.docker/2018-03-07/sessions/eyJhb.../annotations/1836e167-40df-43f6-91ed-d2ced0588914
200 OK
{
"color": "#C31FA8",
"user_name": "Standard User",
"icon": "Comment",
"created_at": "2018-04-11T21:52:13.399Z",
"type": "text",
"document_id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"rect": [[527.66, 715.05], [536.99, 728.39]],
"ctx_and_id": "canvadocs_admin|1836e167-40df-43f6-91ed-d2ced0588914",
"user_id": "standard_user",
"context": "canvadocs_admin",
"@version": "2018-03-07",
"page": 0,
"id": "1836e167-40df-43f6-91ed-d2ced0588914",
"modified_at": "2018-04-11T21:52:13.399Z"
}
Create or Update an Annotation
PUT /2018-03-07/sessions/{session_id}/annotations/{annotation_id}
If the annotation specified by annotation_id already exists, this endpoint updates it. If it does not already exist, it creates a new annotation.
To create a new annotation, the client should randomly generate an ID (UUID V4 recommended) and use that in the request.
Please see the Annotation Types page for a description of what is required for each type of annotation.
Parameters
Query:
session_id: string
annotation_id: string
Body:
Optional:
{
...annotation: Annotation Object,
rotation: number
}
A rotation
parameter may be supplied.
This parameter should be the current rotation value in degrees of the page that the annotation is being left on. This will ensure that if the page has been rotated since the user has opened the session an error will be returned and the annotation will not be saved (preventing an annotation from appearing in undefined locations due to page rotation)
Responses
200
Returns an Annotation Object
400
If the rotation
parameter was supplied and didn't match the document record the following error response will be returned.
{
"error": 'supplied "rotation" value does not match the rotation field of the document record'
}
Example Call
PUT http://canvadocs.docker/2018-03-07/sessions/eyJhb.../annotations/1836e167-40df-43f6-91ed-d2ced0588914
{
"color":"#C31FA8",
"user_name":"Standard User",
"icon":"Comment",
"created_at":"2018-04-11T21:52:13.399Z",
"type":"text",
"document_id":"ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"rect":[[502.31, 710.58],[511.64, 723.92]],
"ctx_and_id":"canvadocs_admin|1836e167-40df-43f6-91ed-d2ced0588914",
"user_id":"standard_user",
"context":"canvadocs_admin",
"@version":"2018-03-07",
"page":0,
"id":"1836e167-40df-43f6-91ed-d2ced0588914",
"modified_at":"2018-04-11T21:52:13.399Z"
}
200 OK
{
"color": "#C31FA8",
"user_name": "Standard User",
"icon": "Comment",
"created_at": "2018-04-11T21:52:13.399Z",
"type": "text",
"document_id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"rect": [[502.31, 710.58], [511.64, 723.92]],
"ctx_and_id": "canvadocs_admin|1836e167-40df-43f6-91ed-d2ced0588914",
"user_id": "standard_user",
"context": "canvadocs_admin",
"@version": "2018-03-07",
"page": 0,
"id": "1836e167-40df-43f6-91ed-d2ced0588914",
"modified_at": "2018-04-11T21:52:13.399Z"
}
Delete an Annotation
DELETE /1/sessions/{session_id}/annotations/{annotation_id}
In order to preserve a record of what has been done (needed for legal reasons by some institutions) annotations are never removed from the database. When an annotation is deleted, it is updated with:
{
deleted: true
deleted_at: TIMESTAMP
deleted_by: USER_NAME
deleted_by_id: USER_ID
}
Annotations that have been deleted (but not delete_acknowledged
) will be shown
only to their owner, with an option to acknowledge the deletion. A delete that
has been acknowledged will not be shown to anyone. If an annotation is
acknowledged or deleted by its creator it is updated with:
{
delete_acknowledged: TIMESTAMP
}
Parameters
Query:
session_id: string
annotation_id: string
Responses
200 OK - The annotation was deleted
204 No Content - The annotation did not exist
Example Call
DELETE http://canvadocs.docker/1/sessions/eyJhb.../annotations/1836e167-40df-43f6-91ed-d2ced0588914
200 OK