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.eprint.getSubmission?uri=at://did:plc:abc123.../pub.chive.eprint.submission/3k5...

XRPC characteristics:

Aspect	Description
Namespace	`pub.chive.*` for all Chive endpoints
Schema	Defined by Lexicons (AT Protocol schemas)
Methods	Query (GET) or Procedure (POST)
Encoding	JSON for data, CBOR for binary

REST

REST endpoints provide a familiar HTTP API for web clients:

GET /api/v1/eprints/at:did:plc:abc123.../pub.chive.eprint.submission/3k5...

REST characteristics:

Aspect	Description
Versioning	`/api/v1/` prefix
Methods	Standard HTTP verbs (GET, POST, PUT, DELETE)
Encoding	JSON
OpenAPI	Full specification at `/openapi.json`

Base URLs

Environment	Base URL
Production	`https://api.chive.pub`
Staging	`https://api.staging.chive.pub`
Local dev	`http://localhost:3000`

Authentication

Chive supports three authentication methods:

Method	Use case	Header
Bearer token	User sessions	`Authorization: Bearer <token>`
Service auth	Server-to-server	`Authorization: Bearer <jwt>`
Unauthenticated	Public 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:

Tier	Requests/minute	Applies to
Anonymous	60	Unauthenticated requests
Authenticated	300	Normal users
Elevated	1000	Verified researchers, institutions
Service	5000	Server-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 Status	Error code	Meaning
400	`InvalidRequest`	Malformed request or missing parameters
401	`AuthRequired`	Authentication needed
403	`Forbidden`	Authenticated but not authorized
404	`NotFound`	Resource doesn't exist
429	`RateLimitExceeded`	Too many requests
500	`InternalError`	Server error

XRPC-specific errors

XRPC endpoints may return AT Protocol error codes:

Error	Meaning
`InvalidToken`	Session token is invalid or expired
`ExpiredToken`	Token has expired; refresh required
`RecordNotFound`	The requested record doesn't exist
`RepoNotFound`	The DID's repository wasn't found

Pagination

List endpoints use cursor-based pagination:

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

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

To fetch the next page:

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

Pagination parameters:

Parameter	Type	Default	Max
`limit`	integer	25	100
`cursor`	string	(none)	(opaque)

AT URIs

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

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

When passing AT URIs as URL parameters, encode them:

/xrpc/pub.chive.eprint.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-Type	Usage
`application/json`	Default for all requests/responses
`application/cbor`	Binary data (blobs)
`multipart/form-data`	File uploads

Endpoint namespaces

XRPC endpoints are organized by namespace:

Namespace	Purpose	Endpoints
`pub.chive.eprint.*`	Eprint operations	3
`pub.chive.review.*`	Reviews, endorsements, and entity links	6
`pub.chive.annotation.*`	Inline annotations and entity links	4
`pub.chive.endorsement.*`	Endorsements	3
`pub.chive.graph.*`	Knowledge graph	10
`pub.chive.tag.*`	User tags	5
`pub.chive.governance.*`	Proposals and voting	16
`pub.chive.metrics.*`	Analytics	8
`pub.chive.discovery.*`	Recommendations	6
`pub.chive.claiming.*`	Authorship claims	19
`pub.chive.backlink.*`	AT Protocol app links	4
`pub.chive.activity.*`	User activity	4
`pub.chive.import.*`	External imports	3
`pub.chive.actor.*`	User profiles	7
`pub.chive.author.*`	Author profiles	2
`pub.chive.sync.*`	Data synchronization	5
`pub.chive.alpha.*`	Alpha tester program	2
`pub.chive.notification.*`	Notifications	2

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

The frontend uses lexicon-generated types for full type safety:

// Import types from schema re-exports
import type { GetSubmissionResponse, EprintRecord, SearchResultsResponse } from '@/lib/api/schema';

// Types are generated from ATProto lexicons
// Source: lexicons/pub/chive/* -> src/lexicons/generated/types/*
// Re-exported: web/lib/api/schema.ts

Type structure

Frontend types flow from lexicons:

lexicons/pub/chive/*.json          # Lexicon definitions
    ↓ (pnpm lexicon:generate)
src/lexicons/generated/types/*     # Generated TypeScript types
    ↓ (re-export)
web/lib/api/schema.ts              # Convenient type aliases
    ↓ (import)
web/components/*                   # React components

Example usage in hooks

// web/lib/hooks/use-eprint.ts
import type { GetSubmissionResponse } from '@/lib/api/schema';

export function useEprint(uri: string) {
  const { data, error } = useSWR<GetSubmissionResponse>(
    `/xrpc/pub.chive.eprint.getSubmission?uri=${encodeURIComponent(uri)}`
  );
  return { eprint: data, error };
}

Regenerating types

After lexicon changes:

# Generate lexicon types (backend)
pnpm lexicon:generate

# Types are re-exported in web/lib/api/schema.ts

Quick examples

Fetch an eprint

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

Search eprints

curl "https://api.chive.pub/xrpc/pub.chive.eprint.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 109 XRPC endpoints (plus REST variants for binary data)

Next steps

Authentication: Session management and tokens
XRPC endpoints: Endpoint overview by namespace
REST endpoints: HTTP API patterns
Interactive API Reference: Full endpoint details

API styles​

XRPC​

REST​

Base URLs​

Authentication​

Rate limiting​

Error handling​

Error response format​

Common error codes​

XRPC-specific errors​

Pagination​

AT URIs​

CORS​

Content types​

Endpoint namespaces​

OpenAPI specification​

SDKs and clients​

TypeScript/JavaScript​

Type structure​

Example usage in hooks​

Regenerating types​

Quick examples​

Fetch an eprint​

Search eprints​

Get recommendations (authenticated)​

Interactive API documentation​

Next steps​