clinstead
API reference

The canonical model, over the wire.

A typed REST API and signed event bus give you read/write access to every canonical entity in your study. The full reference is shipping in stages; the summary below describes the API as it stands today.

Request API accessBase URL: https://api.clinstead.com/v1

  • Typed REST API

    Read and write every entity on the canonical model — studies, instruments, events, participants, signatures. OpenAPI 3.1 spec, fully versioned, with cursor pagination on collection endpoints.

  • Event bus & webhooks

    Subscribe to canonical events (form submitted, query opened, amendment published, agent proposal). Signed webhook deliveries with at-least-once semantics and replay endpoints.

  • Auth & scopes

    OAuth 2.0 client credentials for server-to-server, OIDC for end-user contexts. Scopes are resource-scoped (study:read, queries:write, audit:export) — never tenant-wide unless explicitly granted.

  • Audit-aware writes

    Every write requires reason-for-change where the canonical model demands one. Electronic signatures can be issued via API for non-interactive workflows that have appropriate identity proof.

  • Rate limits & SLAs

    Per-tenant token-bucket rate limits with separate read and write pools. Standard plans 600 req/min read, 120 req/min write. Enterprise plans negotiate higher limits and dedicated quotas.

  • Agent-friendly endpoints

    Operator proposals are first-class API objects. Build custom operators that suggest, review, or escalate — the canonical audit trail ties every action back to the agent identity.

Example

Open a query against a form revision.

A typical write: bearer-token auth, JSON body, reason-for-change in the payload. The same shape works for amendments, signatures, deviation records, and operator proposals.

Responses include the canonical entity id, audit-trail pointer, and version sequence so you can build idempotent clients.

# Open a query against a specific form revision
curl -X POST https://api.clinstead.com/v1/studies/CARDINAL-PHII/queries \
  -H "Authorization: Bearer $CLINSTEAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "SUB-0411",
    "form_id":        "VITALS_V2",
    "field":          "vit_systolic",
    "category":       "out_of_range",
    "reason":         "Reading 220 mmHg flagged by Monitor Bot",
    "assigned_to":    "site:014"
  }'

OpenAPI spec, SDKs, and breaking-change policy

The OpenAPI 3.1 spec, TypeScript and Python SDKs, and our breaking-change policy are available to customers and integration partners under NDA while we finalise the public release.

api@clinstead.comBack to documentation