Skip to main content

XRPC endpoints

This page documents all XRPC endpoints available in the Chive API. Endpoints are organized by namespace.

Preprint namespace

Endpoints for querying preprint submissions.

pub.chive.preprint.getSubmission

Retrieve a single preprint by its AT URI.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesAT URI of the preprint

Response

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"cid": "bafyreib...",
"author": {
"did": "did:plc:abc123...",
"handle": "alice.bsky.social",
"displayName": "Alice Smith"
},
"record": {
"title": "Novel Approach to Quantum Computing",
"abstract": "We present a new method...",
"authors": [...],
"fields": ["cs.QC", "quant-ph"],
"pdfBlob": {
"$type": "blob",
"ref": { "$link": "bafyreib..." },
"mimeType": "application/pdf",
"size": 1234567
},
"createdAt": "2025-01-15T10:30:00Z"
},
"indexedAt": "2025-01-15T10:31:00Z",
"metrics": {
"views": 1234,
"downloads": 456,
"citations": 12
}
}

pub.chive.preprint.searchSubmissions

Search for preprints by query string.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
querystringYesSearch query
fieldsstring[]NoFilter by field codes
authorsstring[]NoFilter by author DIDs
dateFromstringNoStart date (ISO 8601)
dateTostringNoEnd date (ISO 8601)
sortBystringNoSort order: relevance, date, citations
limitintegerNoResults per page (default: 25, max: 100)
cursorstringNoPagination cursor

Response

{
"submissions": [
{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"title": "Novel Approach to Quantum Computing",
"authors": [...],
"abstract": "We present...",
"fields": ["cs.QC"],
"indexedAt": "2025-01-15T10:31:00Z"
}
],
"cursor": "eyJvZmZzZXQiOjI1fQ=="
}

pub.chive.preprint.listByAuthor

List preprints by a specific author.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
authorstringYesAuthor DID
limitintegerNoResults per page (default: 25)
cursorstringNoPagination cursor

Review namespace

Endpoints for peer reviews and comments.

pub.chive.review.getThread

Get a review thread for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesURI of the preprint or root review
depthintegerNoThread depth (default: 6)

Response

{
"thread": {
"uri": "at://did:plc:reviewer.../pub.chive.review.comment/abc...",
"author": {
"did": "did:plc:reviewer...",
"handle": "bob.bsky.social"
},
"record": {
"text": "This is an excellent contribution...",
"subject": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"createdAt": "2025-01-16T14:00:00Z"
},
"replies": [...]
}
}

pub.chive.review.listForPreprint

List all reviews for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI
sortBystringNoSort: recent, helpful
limitintegerNoResults per page
cursorstringNoPagination cursor

Endorsement namespace

Endpoints for formal endorsements.

pub.chive.endorsement.getSummary

Get endorsement summary for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI

Response

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"totalEndorsements": 15,
"byContribution": {
"methodology": 8,
"writing": 5,
"conceptualization": 12,
"data_curation": 3
},
"endorsers": [
{
"did": "did:plc:endorser...",
"handle": "expert.bsky.social",
"contributions": ["methodology", "conceptualization"]
}
]
}

pub.chive.endorsement.listForPreprint

List all endorsements for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI
limitintegerNoResults per page
cursorstringNoPagination cursor

pub.chive.endorsement.getUserEndorsement

Get a specific user's endorsement for a preprint.

PropertyValue
MethodQuery (GET)
AuthRequired

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI
didstringNoUser DID (defaults to authenticated user)

Graph namespace

Endpoints for the knowledge graph.

pub.chive.graph.getField

Get details for a specific field.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
idstringYesField identifier

Response

{
"id": "cs.QC",
"name": "Quantum Computing",
"description": "Research on quantum computation and information",
"aliases": ["Quantum Computation", "QC"],
"parentFields": ["cs", "quant-ph"],
"childFields": ["cs.QC.error-correction", "cs.QC.algorithms"],
"relatedFields": ["cs.CC", "quant-ph.theory"],
"externalIds": {
"wikidata": "Q339",
"lcsh": "sh2008010405"
},
"preprintCount": 4523
}

pub.chive.graph.listFields

List all fields with optional filtering.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
parentstringNoFilter by parent field
querystringNoSearch field names
limitintegerNoResults per page
cursorstringNoPagination cursor

pub.chive.graph.searchAuthorities

Search authority records.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
querystringYesSearch query
typestringNoAuthority type: field, person, organization
limitintegerNoResults per page

pub.chive.graph.getAuthority

Get a specific authority record.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
idstringYesAuthority record ID

pub.chive.graph.browseFaceted

Browse preprints using PMEST facets.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
personalitystring[]NoSubject facets
matterstring[]NoMaterial facets
energystring[]NoProcess facets
spacestring[]NoGeographic facets
timestring[]NoTemporal facets
limitintegerNoResults per page
cursorstringNoPagination cursor

pub.chive.graph.getFieldPreprints

Get preprints in a specific field.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
fieldstringYesField identifier
includeChildrenbooleanNoInclude child fields
sortBystringNoSort order
limitintegerNoResults per page
cursorstringNoPagination cursor

pub.chive.graph.getAuthorityReconciliations

Get reconciliation history for an authority record.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
idstringYesAuthority record ID

Tag namespace

Endpoints for user-generated tags.

pub.chive.tag.search

Search tags.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
querystringYesSearch query
limitintegerNoResults per page

pub.chive.tag.listForPreprint

List tags on a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI

pub.chive.tag.getTrending

Get trending tags.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
periodstringNoTime period: day, week, month
limitintegerNoNumber of tags

pub.chive.tag.getSuggestions

Get tag suggestions based on content.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringNoPreprint URI
textstringNoText to analyze

pub.chive.tag.getDetail

Get details for a specific tag.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
tagstringYesTag name

Governance namespace

Endpoints for community governance.

pub.chive.governance.listProposals

List governance proposals.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
statusstringNoFilter: pending, voting, approved, rejected
typestringNoProposal type
limitintegerNoResults per page
cursorstringNoPagination cursor

pub.chive.governance.getProposal

Get details for a specific proposal.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
idstringYesProposal ID

Response

{
"id": "proposal-123",
"type": "create_field",
"status": "voting",
"proposer": {
"did": "did:plc:proposer...",
"handle": "researcher.bsky.social"
},
"title": "Add Quantum Machine Learning field",
"description": "Propose adding QML as a subfield of both...",
"changes": {
"fieldName": "Quantum Machine Learning",
"parentFields": ["cs.QC", "cs.LG"]
},
"votes": {
"approve": 12,
"reject": 3,
"weightedApprove": 28.5,
"weightedReject": 4.5
},
"threshold": 0.67,
"createdAt": "2025-01-10T09:00:00Z",
"votingEndsAt": "2025-01-17T09:00:00Z"
}

pub.chive.governance.listVotes

List votes on a proposal.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
proposalIdstringYesProposal ID
limitintegerNoResults per page
cursorstringNoPagination cursor

pub.chive.governance.getUserVote

Get the authenticated user's vote on a proposal.

PropertyValue
MethodQuery (GET)
AuthRequired

Parameters

NameTypeRequiredDescription
proposalIdstringYesProposal ID

pub.chive.governance.getPendingCount

Get count of pending proposals.

PropertyValue
MethodQuery (GET)
AuthOptional

Metrics namespace

Endpoints for analytics and engagement metrics.

pub.chive.metrics.getMetrics

Get metrics for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI

Response

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"views": 12453,
"downloads": 3421,
"citations": 45,
"endorsements": 23,
"reviews": 8,
"shares": 156,
"history": {
"views": [
{ "date": "2025-01-14", "count": 234 },
{ "date": "2025-01-15", "count": 456 }
]
}
}

pub.chive.metrics.getViewCount

Get view count for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI

pub.chive.metrics.getTrending

Get trending preprints.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
periodstringNoTime period: day, week, month
fieldstringNoFilter by field
limitintegerNoNumber of results

pub.chive.metrics.recordView

Record a view event.

PropertyValue
MethodProcedure (POST)
AuthOptional

Input

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"source": "search"
}

pub.chive.metrics.recordDownload

Record a download event.

PropertyValue
MethodProcedure (POST)
AuthOptional

Input

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"format": "pdf"
}

pub.chive.metrics.recordSearchClick

Record a search result click.

PropertyValue
MethodProcedure (POST)
AuthOptional

Input

{
"query": "quantum computing",
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"position": 3
}

pub.chive.metrics.recordDwellTime

Record time spent on a preprint.

PropertyValue
MethodProcedure (POST)
AuthOptional

Input

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"durationMs": 45000
}

Discovery namespace

Endpoints for personalized recommendations.

pub.chive.discovery.getRecommendations

Get personalized recommendations for the authenticated user.

PropertyValue
MethodQuery (GET)
AuthRequired

Parameters

NameTypeRequiredDescription
limitintegerNoNumber of recommendations
cursorstringNoPagination cursor

Response

{
"recommendations": [
{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"title": "Advances in Quantum Error Correction",
"reason": "Based on your reading history in quantum computing",
"score": 0.92
}
],
"cursor": "eyJvZmZzZXQiOjIwfQ=="
}

pub.chive.discovery.getSimilar

Get preprints similar to a given preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI
limitintegerNoNumber of results

pub.chive.discovery.getCitations

Get citation graph for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI
directionstringNociting, cited, both
limitintegerNoNumber of results

pub.chive.discovery.getEnrichment

Get enriched metadata for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI

pub.chive.discovery.recordInteraction

Record a user interaction for recommendation training.

PropertyValue
MethodProcedure (POST)
AuthRequired

Input

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"type": "click",
"context": "recommendations"
}

Claiming namespace

Endpoints for authorship claims.

pub.chive.claiming.startClaim

Start a new authorship claim.

PropertyValue
MethodProcedure (POST)
AuthRequired

Input

{
"preprintUri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
"authorPosition": 1,
"orcid": "0000-0002-1825-0097"
}

pub.chive.claiming.getClaim

Get details of a claim.

PropertyValue
MethodQuery (GET)
AuthRequired

Parameters

NameTypeRequiredDescription
idstringYesClaim ID

pub.chive.claiming.completeClaim

Complete a pending claim with verification.

PropertyValue
MethodProcedure (POST)
AuthRequired

pub.chive.claiming.collectEvidence

Collect evidence for a claim.

PropertyValue
MethodProcedure (POST)
AuthRequired

pub.chive.claiming.approveClaim

Approve a claim (moderator only).

PropertyValue
MethodProcedure (POST)
AuthRequired (moderator)

pub.chive.claiming.rejectClaim

Reject a claim (moderator only).

PropertyValue
MethodProcedure (POST)
AuthRequired (moderator)

pub.chive.claiming.getUserClaims

Get claims for the authenticated user.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.claiming.findClaimable

Find preprints claimable by the user.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.claiming.autocomplete

Autocomplete for claim search.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.claiming.searchPreprints

Search preprints for claiming.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.claiming.getSuggestions

Get claim suggestions for the user.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.claiming.startClaimFromExternal

Start a claim from an external identifier.

PropertyValue
MethodProcedure (POST)
AuthRequired

pub.chive.claiming.getPendingClaims

Get pending claims (moderator only).

PropertyValue
MethodQuery (GET)
AuthRequired (moderator)

Endpoints for AT Protocol app references.

List backlinks for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI
sourcestringNoFilter by source app

pub.chive.backlink.create

Create a backlink.

PropertyValue
MethodProcedure (POST)
AuthRequired

pub.chive.backlink.delete

Delete a backlink.

PropertyValue
MethodProcedure (POST)
AuthRequired

pub.chive.backlink.getCounts

Get backlink counts for a preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesPreprint URI

Activity namespace

Endpoints for user activity.

pub.chive.activity.getActivityFeed

Get the user's activity feed.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.activity.logActivity

Log an activity event.

PropertyValue
MethodProcedure (POST)
AuthRequired

pub.chive.activity.getCorrelationMetrics

Get activity correlation metrics.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.activity.markFailed

Mark an activity as failed.

PropertyValue
MethodProcedure (POST)
AuthRequired

Import namespace

Endpoints for importing from external sources.

pub.chive.import.search

Search external sources for preprints.

PropertyValue
MethodQuery (GET)
AuthRequired

Parameters

NameTypeRequiredDescription
querystringYesSearch query
sourcestringNoSource: arxiv, semanticscholar, openalex

pub.chive.import.exists

Check if an external preprint already exists.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
externalIdstringYesExternal identifier (DOI, arXiv ID)

pub.chive.import.get

Get details for an external preprint.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
externalIdstringYesExternal identifier

Actor namespace

Endpoints for user profiles and autocomplete.

pub.chive.actor.getMyProfile

Get the authenticated user's profile.

PropertyValue
MethodQuery (GET)
AuthRequired

Response

{
"did": "did:plc:abc123...",
"handle": "alice.bsky.social",
"displayName": "Alice Smith",
"orcid": "0000-0002-1825-0097",
"affiliation": "MIT",
"bio": "Quantum computing researcher",
"preprintCount": 12,
"endorsementCount": 45
}

pub.chive.actor.autocompleteOrcid

Autocomplete ORCID lookup.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
querystringYesPartial name or ORCID

pub.chive.actor.discoverAuthorIds

Discover external author identifiers.

PropertyValue
MethodQuery (GET)
AuthRequired

pub.chive.actor.autocompleteAffiliation

Autocomplete institution names.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
querystringYesPartial institution name

pub.chive.actor.autocompleteKeyword

Autocomplete research keywords.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
querystringYesPartial keyword

Author namespace

Endpoints for public author profiles.

pub.chive.author.getProfile

Get a public author profile.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
didstringYesAuthor DID

Sync namespace

Endpoints for data synchronization.

pub.chive.sync.checkStaleness

Check if indexed data is stale.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesRecord URI

pub.chive.sync.verify

Verify a record against PDS.

PropertyValue
MethodQuery (GET)
AuthOptional

Parameters

NameTypeRequiredDescription
uristringYesRecord URI

pub.chive.sync.refreshRecord

Force refresh a record from PDS.

PropertyValue
MethodProcedure (POST)
AuthRequired (service)

Input

{
"uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5..."
}

Error codes

All endpoints may return these error codes:

CodeHTTP StatusDescription
InvalidRequest400Malformed request
AuthRequired401Authentication needed
InvalidToken401Token invalid or expired
Forbidden403Not authorized
RecordNotFound404Record doesn't exist
RateLimitExceeded429Too many requests
InternalError500Server error

Next steps