Documentation

Machine-readable: OpenAPI 3.1 · Live capacity: /health/v1/status · Fixtures: /health/v1/sandbox

Quickstart

KEY=$(curl -s https://animica.dev/health/v1/sandbox/signup -H 'content-type: application/json' \
  -d '{"name":"Acme Health"}' | jq -r .api_key)

curl -s https://animica.dev/health/v1/documents/structure \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"execution_class":"HEALTH_PUBLIC","text":"DISCHARGE SUMMARY\n\nCHIEF COMPLAINT:\nChest pain"}'

Authentication

Authorization: Bearer ahk_... or X-Api-Key: ahk_.... Keys are scoped; a key can be narrower than the person who created it, and a key's max_execution_class can pin an integration to HEALTH_PUBLIC so it is structurally incapable of sending PHI. Animica stores only sha256(key).

The healthcare security model

Every request resolves to an execution class before anything else happens.

Step	What happens
1. Class	A PHI-capable operation with no stated class becomes `HEALTH_SECURE`. A public-data operation asked to run `HEALTH_SECURE` is refused, not upgraded — if you think you are protecting PHI on a literature search you need to know you are not.
2. Permission	Secure work requires the organization to be `BAA_ACTIVE` and the key to be secure-scoped. Both, not either.
3. Residency	A hard boundary. An organization pinned to a region cannot widen it, even by asking.
4. Retention	`none` (nothing persisted), `transient`, or `customer_defined`. Anything persisted is AES-256-GCM encrypted with a per-job key.
5. Routing	The scheduler returns an approved provider of the right class in the right region, or it throws. There is no third outcome.

The failure mode is the guarantee. No secure capacity means 503 SECURE_CAPACITY_UNAVAILABLE. No capacity in your region means 503 RESIDENCY_CAPACITY_UNAVAILABLE. Neither ever falls back to public compute.

Execution receipts

Every completed workload returns a signed receipt naming the exact model artifact hash that ran, the execution class, the policy version, the provider and its attestation, and salted commitments to your input and output. The commitment salt is returned to you once, in that response — it is never in the receipt and never anchored, so a receipt discloses nothing about what it is about, while you can still prove the link.

{
  "version": "AHR1",
  "receipt_id": "hrcpt_...",
  "execution_class": "HEALTH_SECURE",
  "model_id": "health-document-structure",
  "model_version": 1,
  "model_hash": "8f3c...",
  "input_commitment": "ahc1:9a41...",
  "output_commitment": "ahc1:1d77...",
  "policy_version": "ahp-2026.08.31",
  "provider_attestation": { "provider_id": "prv_...", "attestation_verified": false },
  "receipt_signature": { "alg": "ml_dsa_65", "verifiable_by": "anyone", ... }
}

Verify at /health/verify, at POST /health/v1/provenance/verify (free, no account), or offline with the CLI. Verification returns a per-property verdict, never a bare boolean: a verifier that could not run is reported as unavailable, never as a forgery.

Endpoints

Endpoint	What it does	PHI
POST /health/v1/fhir/validate	Structural FHIR R4 validation with path-level errors	yes
POST /health/v1/fhir/transform	Declared, provenance-preserving transformations	yes
POST /health/v1/deidentify	De-identification assistance (REDACT / TOKENIZE / PSEUDONYMIZE)	yes
POST /health/v1/documents/structure	Sections, fields, timeline, abbreviations	yes
POST /health/v1/documents/classify	Document type with the evidence that produced it	yes
POST /health/v1/inference	Run a registered healthcare model	yes
POST /health/v1/batch	One operation over many items, one policy	yes
POST /health/v1/terminology/search\|map	Search and crosswalk loaded vocabularies	no
POST /health/v1/literature/search\|summarize	PubMed retrieval and claim-labelled synthesis	no
POST /health/v1/trials/search\|summarize	ClinicalTrials.gov retrieval and structured criteria	no
POST /health/v1/provenance/verify	Verify a receipt. Free, unauthenticated.	no

Errors

Code	HTTP	What to do
SECURE_CAPACITY_UNAVAILABLE	503	Retry later or provision secure capacity. Never retry as HEALTH_PUBLIC unless your policy genuinely permits it.
RESIDENCY_CAPACITY_UNAVAILABLE	503	Provision capacity in that region.
POLICY_VIOLATION	403	The request is not permitted for this organization or key. The body names which condition failed.
MODEL_NOT_ALLOWED	403	That model is not approved for that class, task or deployment.
PROVIDER_NOT_APPROVED	503	The selected provider is not APPROVED. Operator action required.
INVALID_FHIR	400	See `issues[]`.
QUOTA_EXCEEDED / RATE_LIMITED	429	Back off; `Retry-After` is set on rate limits.
RECEIPT_INVALID	400	The receipt is malformed. A receipt that is well-formed but does not verify returns 200 with `valid:false`.

Error bodies never echo your request content. A JSON parse failure says "the request body is not valid JSON" rather than quoting the bytes that failed — because for a health payload those bytes are the thing we must not put in your logs.

SDKs

pip install animica-health
npm install @animica/health

from animica_health import AnimicaHealth

client = AnimicaHealth(api_key="ahk_test_YOUR_KEY", base_url="https://animica.dev")

result = client.inference(
    model="health-document-structure",
    input=open("discharge_summary.txt").read(),
    execution_class="HEALTH_SECURE",
)
print(result.output)
print(result.receipt["receipt_id"], result.receipt["model_hash"])

# Verify the receipt without trusting the response you just got:
print(client.verify(result.receipt, input=..., salt=result.commitment_salt))

Private deployment

Run the execution workers inside your own network; orchestration, policy, receipts and billing stay here, and sensitive data never leaves your infrastructure.

npx @animica/health-worker install
npx @animica/health-worker configure --endpoint https://worker.internal.acme.example \
    --region CUSTOMER_PRIVATE --isolation dedicated_host
npx @animica/health-worker start

The worker registers itself as PENDING. An Animica operator approves it into your organization's private pool, and your organization is then pinned to that pool: your secure work can run nowhere else, enforced in the scheduler's SQL rather than in application logic.

Rate limits and quotas

Per-key token bucket, durable across restarts, default 120 rpm and configurable per key. Monthly metered-unit quotas come from the plan and are checked before execution, so you are never charged for a call that was going to be refused.

Compliance

See /health/compliance. Animica holds no HIPAA, SOC 2, HITRUST or FDA certification and that page says exactly which technical controls exist today and what external work any such certification would require.