pub.chive.annotation.listForEprint

chive.pub

Documentation

List annotations for a specific eprint with optional filtering

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

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.

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

Annotation AT-URI

View raw schema 
{
  "type": "object",
  "required": [
    "uri",
    "cid",
    "author",
    "eprintUri",
    "content",
    "motivation",
    "target",
    "replyCount",
    "createdAt",
    "indexedAt"
  ],
  "properties": {
    "cid": {
      "type": "string",
      "description": "Content identifier"
    },
    "uri": {
      "type": "string",
      "format": "at-uri",
      "description": "Annotation AT-URI"
    },
    "body": {
      "type": "array",
      "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,
      "description": "Rich text body items"
    },
    "author": {
      "ref": "#authorRef",
      "type": "ref"
    },
    "target": {
      "ref": "#textSpanTarget",
      "type": "ref",
      "description": "Target text span for the annotation"
    },
    "content": {
      "type": "string",
      "description": "Plain text content of the annotation"
    },
    "deleted": {
      "type": "boolean",
      "default": false,
      "description": "Whether this annotation has been deleted (tombstone for thread preservation)"
    },
    "createdAt": {
      "type": "string",
      "format": "datetime",
      "description": "When the annotation was created"
    },
    "eprintUri": {
      "type": "string",
      "format": "at-uri",
      "description": "AT-URI of the annotated eprint"
    },
    "indexedAt": {
      "type": "string",
      "format": "datetime",
      "description": "When the annotation was indexed"
    },
    "motivation": {
      "type": "string",
      "description": "W3C Web Annotation motivation",
      "knownValues": [
        "commenting",
        "highlighting",
        "questioning",
        "replying",
        "assessing",
        "bookmarking",
        "classifying",
        "describing",
        "editing",
        "moderating",
        "tagging"
      ]
    },
    "replyCount": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of direct replies"
    },
    "bodyPlainText": {
      "type": "string",
      "description": "Plain text body for search/preview"
    },
    "parentAnnotationUri": {
      "type": "string",
      "format": "at-uri",
      "description": "Parent annotation URI for threaded replies"
    }
  },
  "description": "View of an annotation/comment"
}
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 
{
  "type": "object",
  "required": [
    "type",
    "did",
    "displayName"
  ],
  "properties": {
    "did": {
      "type": "string",
      "format": "did",
      "description": "Author's DID"
    },
    "type": {
      "type": "string",
      "const": "author"
    },
    "orcid": {
      "type": "string",
      "description": "Author's ORCID (if available)"
    },
    "handle": {
      "type": "string",
      "format": "handle",
      "description": "Author's handle"
    },
    "displayName": {
      "type": "string",
      "description": "Author's display name"
    }
  },
  "description": "Link to an ATProto author"
}
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 
{
  "type": "object",
  "required": [
    "did"
  ],
  "properties": {
    "did": {
      "type": "string",
      "format": "did"
    },
    "avatar": {
      "type": "string",
      "format": "uri"
    },
    "handle": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    }
  }
}
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 
{
  "type": "object",
  "required": [
    "x1",
    "y1",
    "x2",
    "y2",
    "width",
    "height",
    "pageNumber"
  ],
  "properties": {
    "x1": {
      "type": "string",
      "description": "Left edge coordinate (as string to preserve float precision)"
    },
    "x2": {
      "type": "string",
      "description": "Right edge coordinate (as string to preserve float precision)"
    },
    "y1": {
      "type": "string",
      "description": "Top edge coordinate (as string to preserve float precision)"
    },
    "y2": {
      "type": "string",
      "description": "Bottom edge coordinate (as string to preserve float precision)"
    },
    "width": {
      "type": "string",
      "description": "Page width reference (as string to preserve float precision)"
    },
    "height": {
      "type": "string",
      "description": "Page height reference (as string to preserve float precision)"
    },
    "pageNumber": {
      "type": "integer",
      "minimum": 1,
      "description": "1-indexed page number for the bounding rectangle"
    }
  },
  "description": "Bounding rectangle coordinates for highlight positioning. All values stored as strings to preserve floating-point precision since ATProto only supports integer type."
}
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

target ref #textSpanTarget Required

Target text span linked to the entity

uri string at-uri Required

Entity link AT-URI

View raw schema 
{
  "type": "object",
  "required": [
    "uri",
    "cid",
    "creator",
    "eprintUri",
    "target",
    "linkedEntity",
    "createdAt",
    "indexedAt"
  ],
  "properties": {
    "cid": {
      "type": "string",
      "description": "Content identifier"
    },
    "uri": {
      "type": "string",
      "format": "at-uri",
      "description": "Entity link AT-URI"
    },
    "target": {
      "ref": "#textSpanTarget",
      "type": "ref",
      "description": "Target text span linked to the entity"
    },
    "creator": {
      "ref": "#authorRef",
      "type": "ref",
      "description": "Creator of the entity link"
    },
    "createdAt": {
      "type": "string",
      "format": "datetime",
      "description": "When the entity link was created"
    },
    "eprintUri": {
      "type": "string",
      "format": "at-uri",
      "description": "AT-URI of the eprint containing the linked text"
    },
    "indexedAt": {
      "type": "string",
      "format": "datetime",
      "description": "When the entity link was indexed"
    },
    "confidence": {
      "type": "integer",
      "maximum": 1000,
      "minimum": 0,
      "description": "Confidence score (0-1000, scaled from 0.0-1.0)"
    },
    "linkedEntity": {
      "refs": [
        "#graphNodeLink",
        "#externalIdLink",
        "#authorLink",
        "#eprintLink"
      ],
      "type": "union",
      "description": "The linked entity"
    }
  },
  "description": "View of an entity link annotation"
}
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 
{
  "type": "object",
  "required": [
    "type",
    "uri",
    "title"
  ],
  "properties": {
    "doi": {
      "type": "string",
      "description": "DOI if available"
    },
    "uri": {
      "type": "string",
      "format": "at-uri",
      "description": "AT-URI of the eprint"
    },
    "type": {
      "type": "string",
      "const": "eprint"
    },
    "title": {
      "type": "string",
      "description": "Eprint title"
    }
  },
  "description": "Link to another eprint/preprint"
}
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 
{
  "type": "object",
  "required": [
    "type",
    "system",
    "identifier",
    "label"
  ],
  "properties": {
    "uri": {
      "type": "string",
      "format": "uri",
      "description": "Full URI for the external entity"
    },
    "type": {
      "type": "string",
      "const": "externalId"
    },
    "label": {
      "type": "string",
      "description": "Display label for the entity"
    },
    "system": {
      "type": "string",
      "description": "External identifier system",
      "knownValues": [
        "wikidata",
        "ror",
        "orcid",
        "isni",
        "viaf",
        "lcsh",
        "fast",
        "credit",
        "spdx",
        "fundref",
        "mesh",
        "aat",
        "gnd",
        "anzsrc",
        "arxiv",
        "doi",
        "pmid",
        "pmcid"
      ]
    },
    "identifier": {
      "type": "string",
      "description": "Identifier value (e.g., Q42 for Wikidata)"
    }
  },
  "description": "Link to an external identifier (Wikidata, ROR, ORCID, etc.)"
}
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 
{
  "type": "object",
  "required": [
    "type",
    "uri",
    "label",
    "kind"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Node UUID identifier"
    },
    "uri": {
      "type": "string",
      "format": "at-uri",
      "description": "AT-URI of the graph node"
    },
    "kind": {
      "type": "string",
      "description": "Node kind: 'type' for classifications, 'object' for instances",
      "knownValues": [
        "type",
        "object"
      ]
    },
    "slug": {
      "type": "string",
      "description": "Human-readable slug (e.g., 'computer-science')"
    },
    "type": {
      "type": "string",
      "const": "graphNode"
    },
    "label": {
      "type": "string",
      "description": "Display label for the node"
    },
    "subkind": {
      "type": "string",
      "description": "Subkind slug (e.g., 'field', 'facet', 'institution', 'contribution-type')"
    },
    "subkindUri": {
      "type": "string",
      "format": "at-uri",
      "description": "AT-URI of the subkind type node"
    }
  },
  "description": "Link to a knowledge graph node"
}
linkedEntityRef object

Union wrapper for linked entity references

Properties

View raw schema 
{
  "type": "object",
  "properties": {
    "entity": {
      "refs": [
        "#graphNodeLink",
        "#externalIdLink",
        "#authorLink",
        "#eprintLink"
      ],
      "type": "union"
    }
  },
  "description": "Union wrapper for linked entity references"
}
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 
{
  "type": "object",
  "required": [
    "type",
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "type": "integer",
      "minimum": 0
    },
    "type": {
      "type": "string",
      "const": "TextPositionSelector"
    },
    "start": {
      "type": "integer",
      "minimum": 0
    },
    "pageNumber": {
      "type": "integer",
      "minimum": 0,
      "description": "0-indexed page number in PDF"
    },
    "boundingRect": {
      "ref": "#boundingRect",
      "type": "ref",
      "description": "Bounding rectangle for visual positioning"
    }
  },
  "description": "W3C Text Position Selector with optional page info"
}
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 
{
  "type": "object",
  "required": [
    "type",
    "exact"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "TextQuoteSelector"
    },
    "exact": {
      "type": "string",
      "maxLength": 1000
    },
    "prefix": {
      "type": "string",
      "maxLength": 100
    },
    "suffix": {
      "type": "string",
      "maxLength": 100
    }
  },
  "description": "W3C Text Quote Selector"
}
textSpanTarget object

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

Properties

page integer Optional

0-indexed page number

minimum: 0
source string at-uri Required

Eprint AT-URI

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

Lexicon Garden

@