Skip to main content

REST endpoints

The REST API provides a traditional HTTP interface for web clients. All endpoints are available under /api/v1/.

Base URL​

https://api.chive.pub/api/v1

Authentication​

Include your access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJFUzI1NiIs...

Content types​

RequestResponse
application/jsonapplication/json

Preprints​

Get preprint​

GET /api/v1/preprints/:encodedUri

Retrieve a preprint by its encoded AT URI.

Path parameters

NameTypeDescription
encodedUristringURL-encoded AT URI

Example

curl "https://api.chive.pub/api/v1/preprints/at%3A%2F%2Fdid%3Aplc%3Aabc123...%2Fpub.chive.preprint.submission%2F3k5..."

Response

{
  "uri": "at://did:plc:abc123.../pub.chive.preprint.submission/3k5...",
  "title": "Novel Approach to Quantum Computing",
  "authors": [
    {
      "did": "did:plc:abc123...",
      "name": "Alice Smith",
      "orcid": "0000-0002-1825-0097"
    }
  ],
  "abstract": "We present a new method...",
  "fields": ["cs.QC", "quant-ph"],
  "pdf": {
    "url": "https://cdn.chive.pub/blobs/bafyreib...",
    "size": 1234567
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "metrics": {
    "views": 1234,
    "downloads": 456,
    "citations": 12
  }
}

Search preprints​

GET /api/v1/preprints

Search and filter preprints.

Query parameters

NameTypeDescription
qstringSearch query
fieldstringFilter by field
authorstringFilter by author DID
fromstringStart date (ISO 8601)
tostringEnd date (ISO 8601)
sortstringSort: relevance, date, citations
pageintegerPage number (1-indexed)
limitintegerResults per page (max 100)

Example

curl "https://api.chive.pub/api/v1/preprints?q=quantum+computing&field=cs.QC&limit=10"

Response

{
  "results": [...],
  "total": 1234,
  "page": 1,
  "pages": 124,
  "limit": 10
}

Get preprint PDF​

GET /api/v1/preprints/:encodedUri/pdf

Redirect to the preprint PDF blob.

Response

302 redirect to blob URL.

Get preprint metrics​

GET /api/v1/preprints/:encodedUri/metrics

Get engagement metrics for a preprint.

Reviews​

Get reviews for preprint​

GET /api/v1/preprints/:encodedUri/reviews

List reviews for a preprint.

Query parameters

NameTypeDescription
sortstringSort: recent, helpful
pageintegerPage number
limitintegerResults per page

Get review thread​

GET /api/v1/reviews/:encodedUri

Get a review and its replies.

Endorsements​

Get endorsements for preprint​

GET /api/v1/preprints/:encodedUri/endorsements

List endorsements for a preprint.

Get endorsement summary​

GET /api/v1/preprints/:encodedUri/endorsements/summary

Get aggregated endorsement data.

Response

{
  "total": 15,
  "byContribution": {
    "methodology": 8,
    "writing": 5,
    "conceptualization": 12
  }
}

Fields​

List fields​

GET /api/v1/fields

List all fields in the knowledge graph.

Query parameters

NameTypeDescription
parentstringFilter by parent field
qstringSearch field names

Get field​

GET /api/v1/fields/:id

Get details for a specific field.

Response

{
  "id": "cs.QC",
  "name": "Quantum Computing",
  "description": "Research on quantum computation",
  "parentFields": ["cs"],
  "childFields": ["cs.QC.algorithms"],
  "preprintCount": 4523
}

Get field preprints​

GET /api/v1/fields/:id/preprints

Get preprints in a field.

Authors​

Get author profile​

GET /api/v1/authors/:did

Get a public author profile.

Response

{
  "did": "did:plc:abc123...",
  "handle": "alice.bsky.social",
  "displayName": "Alice Smith",
  "affiliation": "MIT",
  "orcid": "0000-0002-1825-0097",
  "preprintCount": 12,
  "citationCount": 456
}

Get author preprints​

GET /api/v1/authors/:did/preprints

List preprints by an author.

Tags​

Search tags​

GET /api/v1/tags

Search and list tags.

Query parameters

NameTypeDescription
qstringSearch query
trendingbooleanShow trending tags

Get tag details​

GET /api/v1/tags/:tag

Get details for a specific tag.

Discovery​

Get recommendations​

GET /api/v1/recommendations

Get personalized recommendations (requires auth).

Query parameters

NameTypeDescription
limitintegerNumber of recommendations

Get similar preprints​

GET /api/v1/preprints/:encodedUri/similar

Get preprints similar to a given one.

GET /api/v1/trending

Get trending preprints.

Query parameters

NameTypeDescription
periodstringTime period: day, week, month
fieldstringFilter by field

Governance​

List proposals​

GET /api/v1/governance/proposals

List governance proposals.

Query parameters

NameTypeDescription
statusstringFilter by status
typestringFilter by proposal type

Get proposal​

GET /api/v1/governance/proposals/:id

Get details for a proposal.

User​

Get current user​

GET /api/v1/me

Get the authenticated user's profile.

Get user activity​

GET /api/v1/me/activity

Get the user's activity feed.

Get user claims​

GET /api/v1/me/claims

Get the user's authorship claims.

GET /api/v1/preprints/:encodedUri/backlinks

Get backlinks (AT Protocol app references) for a preprint.

Response

{
  "backlinks": [
    {
      "source": "bsky.app",
      "uri": "at://did:plc:user.../app.bsky.feed.post/xyz...",
      "createdAt": "2025-01-16T12:00:00Z"
    }
  ],
  "counts": {
    "bsky.app": 23,
    "other": 5
  }
}

Import​

Search external sources​

GET /api/v1/import/search

Search external sources (arXiv, Semantic Scholar).

Query parameters

NameTypeDescription
qstringSearch query
sourcestringSource: arxiv, semanticscholar

Check if exists​

GET /api/v1/import/exists

Check if an external preprint exists in Chive.

Query parameters

NameTypeDescription
doistringDOI
arxivstringarXiv ID

Pagination​

REST endpoints use page-based pagination:

{
  "results": [...],
  "total": 1234,
  "page": 1,
  "pages": 124,
  "limit": 10
}
FieldDescription
totalTotal number of results
pageCurrent page (1-indexed)
pagesTotal number of pages
limitResults per page

Error responses​

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Preprint not found",
    "details": {
      "uri": "at://did:plc:abc123..."
    }
  }
}

HTTP status codes​

StatusMeaning
200Success
201Created
204No content
400Bad request
401Unauthorized
403Forbidden
404Not found
429Rate limited
500Server error

Rate limits​

Rate limits apply per IP or per user:

TierRequests/minute
Anonymous60
Authenticated300

Headers included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1704412800

OpenAPI specification​

The complete OpenAPI 3.1 specification is available at:

https://api.chive.pub/openapi.json

Use this for code generation and API exploration.

Next steps​