Animind AI
Sign in

API

Everything the apps do, your pipeline can do.

A versioned REST API generated from the same schemas the service validates against, so the published contract cannot drift from the implementation.

OpenAPI documentGet an API key

Authentication

Either a bearer access token from a user session, or an API key in x-api-key. API keys carry scopes and are additionally constrained by them, so a leaked key is never as powerful as the account that issued it. The raw key is shown exactly once at creation and is not recoverable.

The interpretation contract

Every analysis returns the same structured document: a primary interpretation with a confidence, emotional states, likely intents, urgency, the evidence for and against, alternative interpretations, recommended next observations, safety guidance, limitations, data completeness, and the model and adapter versions.

Clients must surface limitations and safety_guidance alongside any result they display, and must present insufficient_evidence: true as a valid outcome rather than hiding it.

Typical flow

  1. POST /v1/observations — create a draft, optionally against an animal profile.
  2. POST /v1/observations/:id/media — request a signed upload URL, then PUT the bytes directly to storage.
  3. POST /v1/media/:mediaId/complete — the server verifies size, type and checksum.
  4. PATCH /v1/observations/:id/context — add structured context.
  5. POST /v1/observations/:id/submit — queue the analysis.
  6. GET /v1/observations/:id/progress/stream — real stage transitions over Server-Sent Events, or poll the non-streaming endpoint.
  7. GET /v1/observations/:id/interpretation — the structured result.
  8. POST /v1/feedback — report what happened next.

Webhooks

Subscribe to observation.completed, observation.failed, interpretation.created, alert.raised, report.ready and annotation.submitted. Each delivery is signed with HMAC-SHA256 over the raw request body in x-animind-signature. Endpoints must be HTTPS and must not resolve to a private or loopback address.

SDKs

TypeScript and Python SDKs wrap the same contract, including the signed-upload flow and progress streaming with an automatic polling fallback where Server-Sent Events are unavailable.

Rate limits

Requests are limited per authenticated identity rather than per IP, so a shared network does not throttle everyone behind it. Daily request allowances vary by plan. A 429 carries the retry window in its message.