Skip to main content

API overview

Chive exposes two API styles: XRPC (AT Protocol native) and REST (traditional HTTP). Both provide access to the same underlying functionality.

API styles​

XRPC​

XRPC (Cross-Server Remote Procedure Call) is the AT Protocol's native API style. Endpoints follow a namespaced pattern:

/xrpc/pub.chive.preprint.getSubmission?uri=at://did:plc:abc123.../pub.chive.preprint.submission/3k5...

XRPC characteristics:

AspectDescription
Namespacepub.chive.* for all Chive endpoints
SchemaDefined by Lexicons (AT Protocol schemas)
MethodsQuery (GET) or Procedure (POST)
EncodingJSON for data, CBOR for binary

REST​

REST endpoints provide a familiar HTTP API for web clients:

GET /api/v1/preprints/at:did:plc:abc123.../pub.chive.preprint.submission/3k5...

REST characteristics:

AspectDescription
Versioning/api/v1/ prefix
MethodsStandard HTTP verbs (GET, POST, PUT, DELETE)
EncodingJSON
OpenAPIFull specification at /openapi.json

Base URLs​

EnvironmentBase URL
Productionhttps://api.chive.pub
Staginghttps://api.staging.chive.pub
Local devhttp://localhost:3000

Authentication​

Chive supports three authentication methods:

MethodUse caseHeader
Bearer tokenUser sessionsAuthorization: Bearer <token>
Service authServer-to-serverAuthorization: Bearer <jwt>
UnauthenticatedPublic read operations(none)

Most read operations work without authentication. Write operations and user-specific data require a valid session.

See Authentication for details.

Rate limiting​

Rate limits protect the service and ensure fair usage:

TierRequests/minuteApplies to
Anonymous60Unauthenticated requests
Authenticated300Normal users
Elevated1000Verified researchers, institutions
Service5000Server-to-server (approved apps)

Rate limit headers are included in responses:

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

Error handling​

Error response format​

{
  "error": "InvalidRequest",
  "message": "The 'uri' parameter is required",
  "details": {
    "field": "uri",
    "reason": "missing"
  }
}

Common error codes​

HTTP StatusError codeMeaning
400InvalidRequestMalformed request or missing parameters
401AuthRequiredAuthentication needed
403ForbiddenAuthenticated but not authorized
404NotFoundResource doesn't exist
429RateLimitExceededToo many requests
500InternalErrorServer error

XRPC-specific errors​

XRPC endpoints may return AT Protocol error codes:

ErrorMeaning
InvalidTokenSession token is invalid or expired
ExpiredTokenToken has expired; refresh required
RecordNotFoundThe requested record doesn't exist
RepoNotFoundThe DID's repository wasn't found

Pagination​

List endpoints use cursor-based pagination:

GET /xrpc/pub.chive.preprint.searchSubmissions?query=quantum&limit=25

Response:
{
  "submissions": [...],
  "cursor": "eyJvZmZzZXQiOjI1fQ=="
}

To fetch the next page:

GET /xrpc/pub.chive.preprint.searchSubmissions?query=quantum&limit=25&cursor=eyJvZmZzZXQiOjI1fQ==

Pagination parameters:

ParameterTypeDefaultMax
limitinteger25100
cursorstring(none)(opaque)

AT URIs​

Many endpoints accept or return AT URIs, which identify records in the AT Protocol:

at://did:plc:abc123.../pub.chive.preprint.submission/3k5xyzabc
     └──────┬───────┘  └───────────┬─────────────┘   └───┬────┘
          DID               Collection             Record Key

When passing AT URIs as URL parameters, encode them:

/xrpc/pub.chive.preprint.getSubmission?uri=at%3A%2F%2Fdid%3Aplc%3Aabc123...

CORS​

The API supports CORS for browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Content types​

Content-TypeUsage
application/jsonDefault for all requests/responses
application/cborBinary data (blobs)
multipart/form-dataFile uploads

Endpoint namespaces​

XRPC endpoints are organized by namespace:

NamespacePurposeEndpoints
pub.chive.preprint.*Preprint operations4
pub.chive.review.*Reviews and comments2
pub.chive.endorsement.*Endorsements3
pub.chive.graph.*Knowledge graph8
pub.chive.tag.*User tags5
pub.chive.governance.*Proposals and voting5
pub.chive.metrics.*Analytics7
pub.chive.discovery.*Recommendations5
pub.chive.claiming.*Authorship claims12
pub.chive.backlink.*AT Protocol app links4
pub.chive.activity.*User activity4
pub.chive.import.*External imports3
pub.chive.actor.*User profiles5
pub.chive.author.*Author profiles1
pub.chive.sync.*Data synchronization3

See XRPC endpoints for the complete reference.

OpenAPI specification​

The full OpenAPI 3.1 specification is available at:

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

Use this for:

  • Generating client libraries
  • API exploration tools (Swagger UI, Postman)
  • Type generation (openapi-typescript)

SDKs and clients​

TypeScript/JavaScript​

import { ChiveClient } from '@chive/api-client';

const client = new ChiveClient({
  baseUrl: 'https://api.chive.pub',
  token: 'your-session-token'
});

const preprint = await client.preprint.getSubmission({
  uri: 'at://did:plc:abc123.../pub.chive.preprint.submission/3k5...'
});

Generated types​

Frontend types are auto-generated from the OpenAPI spec:

# Regenerate types after API changes
pnpm openapi:generate

Generated files:

  • web/lib/api/schema.generated.ts: Path types (auto-generated)
  • web/lib/api/schema.d.ts: Domain types (manually maintained)
  • web/lib/api/client.ts: Typed API client

Quick examples​

Fetch a preprint​

curl "https://api.chive.pub/xrpc/pub.chive.preprint.getSubmission?uri=at://did:plc:abc123.../pub.chive.preprint.submission/3k5..."

Search preprints​

curl "https://api.chive.pub/xrpc/pub.chive.preprint.searchSubmissions?query=quantum+computing&limit=10"

Get recommendations (authenticated)​

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.chive.pub/xrpc/pub.chive.discovery.getRecommendations?limit=20"

Interactive API documentation​

For detailed endpoint documentation with request/response examples and schemas, see the Interactive API Reference. This documentation is auto-generated from the OpenAPI specification and includes:

  • Request parameters and body schemas
  • Response schemas with examples
  • Try-it-out functionality
  • All 69 XRPC and REST endpoints

Next steps​