pub.chive.annotation.listForEprint Documentation (EN)

main query

List annotations for a specific eprint with optional filtering

Parameters

cursor string Optional

Pagination cursor for next page

eprintUri string at-uri Required

AT-URI of the eprint

includeEntityLinks boolean Optional

Include entity link annotations in response

limit integer Optional

Maximum number of results to return

motivation string Optional

Filter by annotation motivation

pageNumber integer Optional

Filter to specific page number

Output

Encodingapplication/json

annotations array Required

List of annotations for the eprint

cursor string Optional

Cursor for next page

entityLinks array Optional

Included when includeEntityLinks=true

hasMore boolean Required

Whether more results are available

total integer Optional

Total number of annotations for this eprint

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://api.bsky.social)

Parameters

cursor Pagination cursor for next page

eprintUri * AT-URI of the eprint

includeEntityLinks Include entity link annotations in response

limit Maximum number of results to return

motivation Filter by annotation motivation

pageNumber Filter to specific page number

View raw schema

{
  "description": "List annotations for a specific eprint with optional filtering",
  "errors": [],
  "output": {
    "encoding": "application/json",
    "schema": {
      "properties": {
        "annotations": {
          "description": "List of annotations for the eprint",
          "items": {
            "ref": "#annotationView",
            "type": "ref"
          },
          "type": "array"
        },
        "cursor": {
          "description": "Cursor for next page",
          "type": "string"
        },
        "entityLinks": {
          "description": "Included when includeEntityLinks=true",
          "items": {
            "ref": "#entityLinkView",
            "type": "ref"
          },
          "type": "array"
        },
        "hasMore": {
          "description": "Whether more results are available",
          "type": "boolean"
        },
        "total": {
          "description": "Total number of annotations for this eprint",
          "type": "integer"
        }
      },
      "required": [
        "annotations",
        "hasMore"
      ],
      "type": "object"
    }
  },
  "parameters": {
    "properties": {
      "cursor": {
        "description": "Pagination cursor for next page",
        "type": "string"
      },
      "eprintUri": {
        "description": "AT-URI of the eprint",
        "format": "at-uri",
        "type": "string"
      },
      "includeEntityLinks": {
        "default": false,
        "description": "Include entity link annotations in response",
        "type": "boolean"
      },
      "limit": {
        "default": 50,
        "description": "Maximum number of results to return",
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      },
      "motivation": {
        "description": "Filter by annotation motivation",
        "knownValues": [
          "commenting",
          "questioning",
          "highlighting",
          "replying"
        ],
        "type": "string"
      },
      "pageNumber": {
        "description": "Filter to specific page number",
        "minimum": 1,
        "type": "integer"
      }
    },
    "required": [
      "eprintUri"
    ],
    "type": "params"
  },
  "type": "query"
}

annotationView object

View of an annotation/comment

Properties

author ref #authorRef Required

No description available.

body array of union Optional

Rich text body items

maxLength: 500 items

Known types:

bodyPlainText string Optional

Plain text body for search/preview

cid string Required

Content identifier

content string Required

Plain text content of the annotation

createdAt string datetime Required

When the annotation was created

deleted boolean Optional

Whether this annotation has been deleted (tombstone for thread preservation)

eprintUri string at-uri Required

AT-URI of the annotated eprint

indexedAt string datetime Required

When the annotation was indexed

motivation string Required

W3C Web Annotation motivation

Known values: commenting, highlighting, questioning, replying, assessing, bookmarking, classifying, describing, editing, moderating, tagging

parentAnnotationUri string at-uri Optional

Parent annotation URI for threaded replies

replyCount integer Required

Number of direct replies

minimum: 0

target ref #textSpanTarget Required

Target text span for the annotation

uri string at-uri Required

Annotation AT-URI

View raw schema

{
  "description": "View of an annotation/comment",
  "properties": {
    "author": {
      "ref": "#authorRef",
      "type": "ref"
    },
    "body": {
      "description": "Rich text body items",
      "items": {
        "refs": [
          "pub.chive.richtext.defs#textItem",
          "pub.chive.richtext.defs#nodeRefItem",
          "pub.chive.richtext.defs#wikidataRefItem",
          "pub.chive.richtext.defs#fieldRefItem",
          "pub.chive.richtext.defs#facetRefItem",
          "pub.chive.richtext.defs#eprintRefItem",
          "pub.chive.richtext.defs#annotationRefItem",
          "pub.chive.richtext.defs#authorRefItem",
          "pub.chive.richtext.defs#mentionItem",
          "pub.chive.richtext.defs#linkItem",
          "pub.chive.richtext.defs#tagItem",
          "pub.chive.richtext.defs#latexItem",
          "pub.chive.richtext.defs#codeBlockItem",
          "pub.chive.richtext.defs#headingItem",
          "pub.chive.richtext.defs#listItem",
          "pub.chive.richtext.defs#blockquoteItem"
        ],
        "type": "union"
      },
      "maxLength": 500,
      "type": "array"
    },
    "bodyPlainText": {
      "description": "Plain text body for search/preview",
      "type": "string"
    },
    "cid": {
      "description": "Content identifier",
      "type": "string"
    },
    "content": {
      "description": "Plain text content of the annotation",
      "type": "string"
    },
    "createdAt": {
      "description": "When the annotation was created",
      "format": "datetime",
      "type": "string"
    },
    "deleted": {
      "default": false,
      "description": "Whether this annotation has been deleted (tombstone for thread preservation)",
      "type": "boolean"
    },
    "eprintUri": {
      "description": "AT-URI of the annotated eprint",
      "format": "at-uri",
      "type": "string"
    },
    "indexedAt": {
      "description": "When the annotation was indexed",
      "format": "datetime",
      "type": "string"
    },
    "motivation": {
      "description": "W3C Web Annotation motivation",
      "knownValues": [
        "commenting",
        "highlighting",
        "questioning",
        "replying",
        "assessing",
        "bookmarking",
        "classifying",
        "describing",
        "editing",
        "moderating",
        "tagging"
      ],
      "type": "string"
    },
    "parentAnnotationUri": {
      "description": "Parent annotation URI for threaded replies",
      "format": "at-uri",
      "type": "string"
    },
    "replyCount": {
      "description": "Number of direct replies",
      "minimum": 0,
      "type": "integer"
    },
    "target": {
      "description": "Target text span for the annotation",
      "ref": "#textSpanTarget",
      "type": "ref"
    },
    "uri": {
      "description": "Annotation AT-URI",
      "format": "at-uri",
      "type": "string"
    }
  },
  "required": [
    "uri",
    "cid",
    "author",
    "eprintUri",
    "content",
    "motivation",
    "target",
    "replyCount",
    "createdAt",
    "indexedAt"
  ],
  "type": "object"
}

authorLink object

Link to an ATProto author

Properties

did string did Required

Author's DID

displayName string Required

Author's display name

handle string handle Optional

Author's handle

orcid string Optional

Author's ORCID (if available)

type string Required

No description available.

View raw schema

{
  "description": "Link to an ATProto author",
  "properties": {
    "did": {
      "description": "Author's DID",
      "format": "did",
      "type": "string"
    },
    "displayName": {
      "description": "Author's display name",
      "type": "string"
    },
    "handle": {
      "description": "Author's handle",
      "format": "handle",
      "type": "string"
    },
    "orcid": {
      "description": "Author's ORCID (if available)",
      "type": "string"
    },
    "type": {
      "const": "author",
      "type": "string"
    }
  },
  "required": [
    "type",
    "did",
    "displayName"
  ],
  "type": "object"
}

authorRef object

No description available.

Properties

avatar string uri Optional

A valid URI.

did string did Required

A decentralized identifier (DID).

displayName string Optional

No description available.

handle string Optional

No description available.

View raw schema

{
  "properties": {
    "avatar": {
      "format": "uri",
      "type": "string"
    },
    "did": {
      "format": "did",
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "handle": {
      "type": "string"
    }
  },
  "required": [
    "did"
  ],
  "type": "object"
}

boundingRect object

Bounding rectangle coordinates for highlight positioning. All values stored as strings to preserve floating-point precision since ATProto only supports integer type.

Properties

height string Required

Page height reference (as string to preserve float precision)

pageNumber integer Required

1-indexed page number for the bounding rectangle

minimum: 1

width string Required

Page width reference (as string to preserve float precision)

x1 string Required

Left edge coordinate (as string to preserve float precision)

x2 string Required

Right edge coordinate (as string to preserve float precision)

y1 string Required

Top edge coordinate (as string to preserve float precision)

y2 string Required

Bottom edge coordinate (as string to preserve float precision)

View raw schema

{
  "description": "Bounding rectangle coordinates for highlight positioning. All values stored as strings to preserve floating-point precision since ATProto only supports integer type.",
  "properties": {
    "height": {
      "description": "Page height reference (as string to preserve float precision)",
      "type": "string"
    },
    "pageNumber": {
      "description": "1-indexed page number for the bounding rectangle",
      "minimum": 1,
      "type": "integer"
    },
    "width": {
      "description": "Page width reference (as string to preserve float precision)",
      "type": "string"
    },
    "x1": {
      "description": "Left edge coordinate (as string to preserve float precision)",
      "type": "string"
    },
    "x2": {
      "description": "Right edge coordinate (as string to preserve float precision)",
      "type": "string"
    },
    "y1": {
      "description": "Top edge coordinate (as string to preserve float precision)",
      "type": "string"
    },
    "y2": {
      "description": "Bottom edge coordinate (as string to preserve float precision)",
      "type": "string"
    }
  },
  "required": [
    "x1",
    "y1",
    "x2",
    "y2",
    "width",
    "height",
    "pageNumber"
  ],
  "type": "object"
}

entityLinkView object

View of an entity link annotation

Properties

cid string Required

Content identifier

confidence integer Optional

Confidence score (0-1000, scaled from 0.0-1.0)

minimum: 0maximum: 1000

createdAt string datetime Required

When the entity link was created

creator ref #authorRef Required

Creator of the entity link

eprintUri string at-uri Required

AT-URI of the eprint containing the linked text

indexedAt string datetime Required

When the entity link was indexed

linkedEntity union Required

The linked entity

Known types:

#graphNodeLink
#externalIdLink
#authorLink
#eprintLink

target ref #textSpanTarget Required

Target text span linked to the entity

uri string at-uri Required

Entity link AT-URI

View raw schema

{
  "description": "View of an entity link annotation",
  "properties": {
    "cid": {
      "description": "Content identifier",
      "type": "string"
    },
    "confidence": {
      "description": "Confidence score (0-1000, scaled from 0.0-1.0)",
      "maximum": 1000,
      "minimum": 0,
      "type": "integer"
    },
    "createdAt": {
      "description": "When the entity link was created",
      "format": "datetime",
      "type": "string"
    },
    "creator": {
      "description": "Creator of the entity link",
      "ref": "#authorRef",
      "type": "ref"
    },
    "eprintUri": {
      "description": "AT-URI of the eprint containing the linked text",
      "format": "at-uri",
      "type": "string"
    },
    "indexedAt": {
      "description": "When the entity link was indexed",
      "format": "datetime",
      "type": "string"
    },
    "linkedEntity": {
      "description": "The linked entity",
      "refs": [
        "#graphNodeLink",
        "#externalIdLink",
        "#authorLink",
        "#eprintLink"
      ],
      "type": "union"
    },
    "target": {
      "description": "Target text span linked to the entity",
      "ref": "#textSpanTarget",
      "type": "ref"
    },
    "uri": {
      "description": "Entity link AT-URI",
      "format": "at-uri",
      "type": "string"
    }
  },
  "required": [
    "uri",
    "cid",
    "creator",
    "eprintUri",
    "target",
    "linkedEntity",
    "createdAt",
    "indexedAt"
  ],
  "type": "object"
}

eprintLink object

Link to another eprint/preprint

Properties

doi string Optional

DOI if available

title string Required

Eprint title

type string Required

No description available.

uri string at-uri Required

AT-URI of the eprint

View raw schema

{
  "description": "Link to another eprint/preprint",
  "properties": {
    "doi": {
      "description": "DOI if available",
      "type": "string"
    },
    "title": {
      "description": "Eprint title",
      "type": "string"
    },
    "type": {
      "const": "eprint",
      "type": "string"
    },
    "uri": {
      "description": "AT-URI of the eprint",
      "format": "at-uri",
      "type": "string"
    }
  },
  "required": [
    "type",
    "uri",
    "title"
  ],
  "type": "object"
}

externalIdLink object

Link to an external identifier (Wikidata, ROR, ORCID, etc.)

Properties

identifier string Required

Identifier value (e.g., Q42 for Wikidata)

label string Required

Display label for the entity

system string Required

External identifier system

Known values: wikidata, ror, orcid, isni, viaf, lcsh, fast, credit, spdx, fundref, mesh, aat, gnd, anzsrc, arxiv, doi, pmid, pmcid

type string Required

No description available.

uri string uri Optional

Full URI for the external entity

View raw schema

{
  "description": "Link to an external identifier (Wikidata, ROR, ORCID, etc.)",
  "properties": {
    "identifier": {
      "description": "Identifier value (e.g., Q42 for Wikidata)",
      "type": "string"
    },
    "label": {
      "description": "Display label for the entity",
      "type": "string"
    },
    "system": {
      "description": "External identifier system",
      "knownValues": [
        "wikidata",
        "ror",
        "orcid",
        "isni",
        "viaf",
        "lcsh",
        "fast",
        "credit",
        "spdx",
        "fundref",
        "mesh",
        "aat",
        "gnd",
        "anzsrc",
        "arxiv",
        "doi",
        "pmid",
        "pmcid"
      ],
      "type": "string"
    },
    "type": {
      "const": "externalId",
      "type": "string"
    },
    "uri": {
      "description": "Full URI for the external entity",
      "format": "uri",
      "type": "string"
    }
  },
  "required": [
    "type",
    "system",
    "identifier",
    "label"
  ],
  "type": "object"
}

graphNodeLink object

Link to a knowledge graph node

Properties

id string Optional

Node UUID identifier

kind string Required

Node kind: 'type' for classifications, 'object' for instances

Known values: type, object

label string Required

Display label for the node

slug string Optional

Human-readable slug (e.g., 'computer-science')

subkind string Optional

Subkind slug (e.g., 'field', 'facet', 'institution', 'contribution-type')

subkindUri string at-uri Optional

AT-URI of the subkind type node

type string Required

No description available.

uri string at-uri Required

AT-URI of the graph node

View raw schema

{
  "description": "Link to a knowledge graph node",
  "properties": {
    "id": {
      "description": "Node UUID identifier",
      "type": "string"
    },
    "kind": {
      "description": "Node kind: 'type' for classifications, 'object' for instances",
      "knownValues": [
        "type",
        "object"
      ],
      "type": "string"
    },
    "label": {
      "description": "Display label for the node",
      "type": "string"
    },
    "slug": {
      "description": "Human-readable slug (e.g., 'computer-science')",
      "type": "string"
    },
    "subkind": {
      "description": "Subkind slug (e.g., 'field', 'facet', 'institution', 'contribution-type')",
      "type": "string"
    },
    "subkindUri": {
      "description": "AT-URI of the subkind type node",
      "format": "at-uri",
      "type": "string"
    },
    "type": {
      "const": "graphNode",
      "type": "string"
    },
    "uri": {
      "description": "AT-URI of the graph node",
      "format": "at-uri",
      "type": "string"
    }
  },
  "required": [
    "type",
    "uri",
    "label",
    "kind"
  ],
  "type": "object"
}

linkedEntityRef object

Union wrapper for linked entity references

Properties

entity union Optional

No description available.

Known types:

#graphNodeLink
#externalIdLink
#authorLink
#eprintLink

View raw schema

{
  "description": "Union wrapper for linked entity references",
  "properties": {
    "entity": {
      "refs": [
        "#graphNodeLink",
        "#externalIdLink",
        "#authorLink",
        "#eprintLink"
      ],
      "type": "union"
    }
  },
  "type": "object"
}

textPositionSelector object

W3C Text Position Selector with optional page info

Properties

boundingRect ref #boundingRect Optional

Bounding rectangle for visual positioning

end integer Required

No description available.

minimum: 0

pageNumber integer Optional

0-indexed page number in PDF

minimum: 0

start integer Required

No description available.

minimum: 0

type string Required

No description available.

View raw schema

{
  "description": "W3C Text Position Selector with optional page info",
  "properties": {
    "boundingRect": {
      "description": "Bounding rectangle for visual positioning",
      "ref": "#boundingRect",
      "type": "ref"
    },
    "end": {
      "minimum": 0,
      "type": "integer"
    },
    "pageNumber": {
      "description": "0-indexed page number in PDF",
      "minimum": 0,
      "type": "integer"
    },
    "start": {
      "minimum": 0,
      "type": "integer"
    },
    "type": {
      "const": "TextPositionSelector",
      "type": "string"
    }
  },
  "required": [
    "type",
    "start",
    "end"
  ],
  "type": "object"
}

textQuoteSelector object

W3C Text Quote Selector

Properties

exact string Required

No description available.

maxLength: 1000 bytes

prefix string Optional

No description available.

maxLength: 100 bytes

suffix string Optional

No description available.

maxLength: 100 bytes

type string Required

No description available.

View raw schema

{
  "description": "W3C Text Quote Selector",
  "properties": {
    "exact": {
      "maxLength": 1000,
      "type": "string"
    },
    "prefix": {
      "maxLength": 100,
      "type": "string"
    },
    "suffix": {
      "maxLength": 100,
      "type": "string"
    },
    "type": {
      "const": "TextQuoteSelector",
      "type": "string"
    }
  },
  "required": [
    "type",
    "exact"
  ],
  "type": "object"
}

textSpanTarget object

Target text span for inline annotations (W3C Web Annotation compatible)

Properties

page integer Optional

0-indexed page number

minimum: 0

refinedBy ref #textPositionSelector Optional

Position refinement with page info

selector ref #textQuoteSelector Optional

Text quote selector

source string at-uri Required

Eprint AT-URI

View raw schema

{
  "description": "Target text span for inline annotations (W3C Web Annotation compatible)",
  "properties": {
    "page": {
      "description": "0-indexed page number",
      "minimum": 0,
      "type": "integer"
    },
    "refinedBy": {
      "description": "Position refinement with page info",
      "ref": "#textPositionSelector",
      "type": "ref"
    },
    "selector": {
      "description": "Text quote selector",
      "ref": "#textQuoteSelector",
      "type": "ref"
    },
    "source": {
      "description": "Eprint AT-URI",
      "format": "at-uri",
      "type": "string"
    }
  },
  "required": [
    "source"
  ],
  "type": "object"
}