Skip to content
ChekChek Docs

Add a bookmark or highlight

POST
/api/v1/publications/{publicationId}/annotations
curl --request POST \
  --url http://localhost:8080/api/v1/publications/1/annotations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "bookmark", "locator": { "href": "example", "type": "application/xhtml+xml", "title": "example", "locations": { "fragments": [ "example" ], "progression": 1, "totalProgression": 1, "position": 1 }, "text": { "before": "example", "highlight": "example", "after": "example" } }, "color": "example", "note": "example" }'

A highlight’s locator must carry the highlighted text in text.highlight. A publication holds up to 5,000 annotations per user.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
publicationId
required
integer format: int64

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
kind
required
string
Allowed values: bookmark highlight
locator
required

A Readium Locator. The server checks the fields below and stores the rest as sent, up to 16 KiB in all.

object
href
required
string
>= 1 characters
type
required

The resource’s media type.

string

Example 

application/xhtml+xml
title
string
locations
object
fragments
Array<string>
progression

Position within the resource.

number
<= 1
totalProgression

Position within the publication.

number
<= 1
position
integer
>= 1
text
object
before
string
highlight
string
after
string
color

A color name or value the client chooses, such as yellow.

string
>= 1 characters <= 32 characters
note
string
<= 10000 characters

Responses

Section titled “Responses”

201

Section titled “201”

The new annotation.

Media typeapplication/json
object
id
required
integer format: int64
publicationId
required
integer format: int64
kind
required
string
Allowed values: bookmark highlight
locator
required

A Readium Locator. The server checks the fields below and stores the rest as sent, up to 16 KiB in all.

object
href
required
string
>= 1 characters
type
required

The resource’s media type.

string
title
string
locations
object
fragments
Array<string>
progression

Position within the resource.

number
<= 1
totalProgression

Position within the publication.

number
<= 1
position
integer
>= 1
text
object
before
string
highlight
string
after
string
color
required
string | null
note
required
string | null
device
required

The device name of the session that last saved it.

string | null
createdAt
required
string format: date-time
updatedAt
required
string format: date-time

Example 

{
  "kind": "bookmark",
  "locator": {
    "type": "application/xhtml+xml"
  }
}

400

Section titled “400”

The request was malformed.

Media typeapplication/json
object
code
required
string
Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal
message
required

Explains the problem to a developer.

string

Example 

{
  "code": "bad_request"
}

401

Section titled “401”

The request has no valid session token.

Media typeapplication/json
object
code
required
string
Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal
message
required

Explains the problem to a developer.

string

Example 

{
  "code": "bad_request"
}

403

Section titled “403”

The signed-in user may not do this. demo_account when the user is a shared demo account, named in CHEK_DEMO_USERS, which can’t change its password, sessions, sign-in providers, extensions or annotations.

Media typeapplication/json
object
code
required
string
Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal
message
required

Explains the problem to a developer.

string

Example 

{
  "code": "bad_request"
}

404

Section titled “404”

The resource does not exist.

Media typeapplication/json
object
code
required
string
Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal
message
required

Explains the problem to a developer.

string

Example 

{
  "code": "bad_request"
}

500

Section titled “500”

The server failed; details are in its log.

Media typeapplication/json
object
code
required
string
Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal
message
required

Explains the problem to a developer.

string

Example 

{
  "code": "bad_request"
}