Skip to main content

API Overview

Cluster provides a RESTful API for all operations. The API follows W3C Web Annotation standards for annotation data.

Base URL​

# Development
http://localhost:4000/api

# Production
https://your-domain.com/api

Authentication​

All API requests require a valid Azure AD access token:

Authorization: Bearer <access-token>

See Authentication for details.

Response Format​

Success Response​

{
  "data": { ... },
  "meta": {
    "timestamp": "2025-01-03T14:30:00Z"
  }
}

Collection Response​

{
  "data": [ ... ],
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

Error Response​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid selector type",
    "details": {
      "field": "target.selector.type",
      "received": "InvalidSelector"
    }
  }
}

HTTP Status Codes​

CodeDescription
200Success
201Created
204No Content (successful deletion)
400Bad Request (validation error)
401Unauthorized (missing/invalid token)
403Forbidden (insufficient permissions)
404Not Found
422Unprocessable Entity (semantic error)
500Internal Server Error

Content Types​

Request​

Content-Type: application/json

For W3C annotation operations:

Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"

Response​

Standard responses use JSON:

Content-Type: application/json

W3C annotation responses use JSON-LD:

Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"

API Sections​

Core Resources​

EndpointDescription
/api/annotationsW3C Web Annotations
/api/clustersAnnotation collections (affinity groups)
/api/studiesResearch studies/projects
/api/filesSharePoint file proxy
/api/tagsTag taxonomies
/api/insightsResearch insights

Authentication​

EndpointDescription
/api/auth/meCurrent user info
/api/auth/organizationCurrent organization

Rate Limiting​

Cluster does not impose rate limits by default. Self-hosted deployments can configure rate limiting via reverse proxy (nginx, Traefik).

Pagination​

Collection endpoints support pagination:

GET /api/annotations?offset=20&limit=10
ParameterTypeDefaultDescription
offsetinteger0Skip this many results
limitinteger20Maximum results to return

Filtering​

Most collection endpoints support filtering:

GET /api/annotations?studyId=uuid&motivation=highlighting

Sorting​

Use sortBy and sortOrder parameters:

GET /api/annotations?sortBy=created&sortOrder=desc

CORS​

The API allows cross-origin requests from configured origins:

// Default development
cors({ origin: 'http://localhost:3000' })

// Production - configure in environment
cors({ origin: process.env.WEB_URL })

Versioning​

The API is currently unversioned. Breaking changes will be communicated via changelog and migration guides.

OpenAPI Specification​

An OpenAPI 3.0 specification is available at:

GET /api/openapi.json

Next Steps​