Hosted beta

Hosted API

Go from an API key to a policy decision. Integrate on your server, start in shadow mode, and keep every outcome explicit.

Base URL: https://api.antaeus.io/api/v0.1 · Open the dashboard · API reference

Antaeus evaluates language against your policy and returns allow, review, deny, or failure. Your application owns enforcement and side effects. The hosted service is an experimental beta with shared capacity and no production SLA. Read the limits and prepaid pricing before enabling paid usage.

The legacy /v0alpha1 base remains supported. Both URLs require v0alpha2 request and response formats; keep the apiVersion values shown in the examples. Old payload versions are rejected before evaluation. Policy format remains v0alpha1. The alias has no announced removal date. Retries across either URL share the same operation within the 24-hour replay window when the API key, idempotency key and JSON body are unchanged.

Use an AI assistant? Connect the MCP server to check proposed actions against your approved policy.

Quickstart

1. Create your key

Sign in at app.antaeus.io, create your workspace, and open API keys. Create a key with decisions:create, copy it once, and store it as ANTAEUS_API_KEY in your server’s environment or secret store. Never paste the key into a coding-agent conversation or commit it to Git.

2. Send a synthetic input

Save this as decision-request.json. This inline policy works without first creating a managed policy. It is a demonstration; review your own rules before using them in your application.

{
  "apiVersion": "decision.antaeus.io/v0alpha2",
  "kind": "DecisionRequest",
  "policy": {
    "inline": {
      "apiVersion": "policy.antaeus.io/v0alpha1",
      "kind": "Policy",
      "metadata": { "name": "submission-review" },
      "spec": {
        "defaultOutcome": "review",
        "rules": [
          {
            "id": "contains-threat",
            "when": "The submission text contains a threat of violence against a person.",
            "outcome": "deny"
          },
          {
            "id": "ordinary-product-description",
            "when": "The submission text describes an ordinary software product without threats of violence.",
            "outcome": "allow"
          }
        ]
      }
    }
  },
  "input": { "text": "A calendar app for planning team meetings." }
}

With ANTAEUS_API_KEY already configured, run from your server or terminal:

curl --max-time 20 --include https://api.antaeus.io/api/v0.1/decisions \
  -H "Authorization: Bearer $ANTAEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: submission-demo-001" \
  --data-binary @decision-request.json

HTTP 200 returns a Decision directly, without a wrapper. Read outcome, policy, ruleResults, and reasonCodes; failure also includes failure details. A specific outcome is not guaranteed for this example. Save the X-Request-Id response header and find it in Usage & requests in the dashboard.

The demo key is a logical event ID. Keep it with this exact request for retries; choose a new ID for each new input. Read limits if you receive 429.

3. Connect your application

Start in shadow mode: record the advisory result while preserving existing behavior. Send only the input fields your policy needs. Keep authentication, authorization, exact numeric limits, payment checks, and transactions in your application. Keep significant decisions under human review.

For a maintained policy, open Create a policy under Policies in the dashboard. Draft and test it, approve and publish the exact digest, then copy its integration instructions. Those instructions include the published reference and your synthetic example, never the key. Policy management also supports server-side HTTP sync. The local policy-authoring guide explains the portable format.

Authentication

Use HTTPS and Authorization: Bearer <API key> on every API request. POST and PUT bodies use Content-Type: application/json. Call from your backend; browser CORS access is not provided. Clerk session cookies and JWTs are console credentials, not hosted API keys.

Scope	Allows
`decisions:create`	Evaluate inline or published policies
`policies:read`	Validate, list, and read managed policies and versions
`policies:write`	Create, edit, publish, archive, and restore policies

The runtime key only needs decisions:create. Use a separate write-enabled key for policy maintenance. Keys belong to workspace service accounts; valid credentials still require active workspace authorization. Only the owner creates keys. New and rotated keys have no expiry by default; existing dated keys retain their expiry. Rotation creates a replacement: update your server, verify it works, then revoke the old key. Do not expose keys through public frontend variables, logs, URLs, prompts, or source code.

Decisions

POST /decisions accepts exactly one of policy.inline or policy.reference. Inline is a complete Policy JSON object. Reference selects an immutable version published in your workspace:

{
  "apiVersion": "decision.antaeus.io/v0alpha2",
  "kind": "DecisionRequest",
  "policy": {
    "reference": {
      "name": "your-published-policy-name",
      "digest": "sha256:REPLACE_WITH_THE_PUBLISHED_DIGEST"
    }
  },
  "input": { "text": "Your application's relevant input." }
}

Replace the name and digest with the dashboard’s values. Optional reference.version must match the registry version returned by publication; it is not a policy YAML field. Editing a draft does not change deployed references. Archiving blocks new reference evaluations; restoring re-enables them.

Outcome	Meaning	Application handling after shadow mode
`allow`	The policy reduction permits this input	Continue only after your own authorization and deterministic checks
`review`	The policy requires review, uses its review default, or has uncertainty with no higher-priority deny/failure	Queue for human review; never silently treat as allow
`deny`	The policy reduction denies this input	Block the policy-governed action and expose an appropriate explanation
`failure`	Evaluation did not produce a policy judgment	Use your explicit operational-failure path; never allow automatically

HTTP 200 with review or deny is a completed evaluation. HTTP 200 with failure is still a portable Decision, not an HTTP error. Inspect failure.retryable before considering a new evaluation; replaying the same completed idempotency key returns the same failure. See the released Decision guide and generated API reference for fields and schemas. Evaluator names exposed by the service are versioned Antaeus aliases, not a customer-selectable provider configuration.

Retries and errors

Use a stable Idempotency-Key for every logical evaluation: 1–128 visible ASCII characters (no spaces). Retries must use the same API credential, key, and identical JSON payload, including property order. The replay window is 24 hours. Completed requests return their stored Decision with Idempotency-Replayed: true, no new evaluation, and no additional usage or charge. Completed reference requests can replay after policy archival.

A client timeout does not prove the server stopped. Retry with the same key and body to retrieve the completed result. Duplicates may wait briefly and then return 429 in-progress. An interrupted hold may remain pending for up to 210 seconds. Use a 20-second client timeout and a bounded retry policy with exponential backoff and jitter; respect Retry-After on 429 and 500. Keep the key and body for later diagnosis if retries are exhausted. Retry transport failures and retryable server errors with the same key, never by generating a fresh event ID. Malformed responses are operational failures.

Errors use RFC 9457 Problem Details, not the Decision format:

{
  "type": "https://antaeus.io/problems/in-progress",
  "title": "in-progress",
  "status": 429,
  "detail": "This request is still running. Retry with the same key and body.",
  "requestId": "example-request-id",
  "error": { "code": "in-progress", "message": "This request is still running. Retry with the same key and body." }
}

Match HTTP status and error.code (also the problem title); do not match human-readable detail text. Problem type URIs identify error types; they are not documentation endpoints. Responses include X-Request-Id and Cache-Control: no-store. Log the request ID, digest, outcome/error, and latency rather than raw inputs or credentials.

HTTP status	Meaning	What to do
400	Malformed JSON, request, reference, or idempotency key	Correct the request
401	Invalid, expired, revoked, or internally unauthorized key	Check or rotate the credential
403	Insufficient scope or suspended workspace	Check grants or contact support
404	Missing, archived, or mismatched published policy	Check name, digest, and optional version
409	Draft conflict, duplicate name, or resource limit	Refresh and review before editing; do not blindly overwrite
413	Body, policy, or input too large	Reduce size
415	Unsupported content type	Send `application/json`
422	Invalid policy, evaluation rejection, or idempotency conflict	Correct content; a different logical request needs a new key
429	Quota, rate, concurrency, or shared capacity limit	Respect `Retry-After`; do not busy-loop
500	Authentication, validation, or evaluation unavailable; expired attempt	Retry with the same key and body, using bounded backoff

Do not retry other 4xx without correcting the cause. quota-exhausted, validation-limit, and free-budget-exhausted reset at the next UTC midnight. Busy and in-progress conditions use shorter waits. Shared paid capacity can also return a budget error; prepaid credit does not bypass capacity.

Failover: the current hosted path does not dispatch a backup evaluator on outages. It rejects without a customer charge. Operational errors never fabricate an allow/review/deny Decision. Completed low-confidence or indeterminate evidence returns HTTP 200 with review when there is no matched deny or failed evidence. Matched deny takes precedence; failed evidence retains the failure path. An uncertainty review has evaluation.indeterminate_rule and no failure object. It consumes a check under the existing completed-evaluation rule and, when credit-funded, the existing metered charge. This can bring a top-up forward without changing prices. Provider outages, timeouts and invalid evaluator output remain operational failures, uncharged.

Policy management

Paths below are relative to https://api.antaeus.io/api/v0.1. All need the API key header. Source is a string of constrained YAML or equivalent JSON; inputExample is a synthetic JSON object. The portable policy schema is authoritative. Validate with antaeus validate policy.yaml locally, or use the validation endpoint. Hosted sync currently uses HTTP, not an antaeus sync CLI command.

Method and path	Scope	Body / response
`POST /policies:validate`	`policies:read`	`{ "source": "..." }` returns `{ "policy": { "name", "digest", "rules" } }`
`GET /policies`	`policies:read`	Returns `{ "policies": [...] }`
`POST /policies`	`policies:write`	`{ "source": "...", "inputExample": {} }` returns 201 `{ "policy": {...} }`
`GET /policies/:id`	`policies:read`	Returns `{ "policy": {...}, "versions": [...] }`
`PUT /policies/:id`	`policies:write`	`{ "source": "...", "inputExample": {}, "revision": 1 }` returns `{ "policy": {...} }`
`POST /policies/:id/publish`	`policies:write`	`{ "digest": "sha256:..." }` returns `{ "versions": [...] }`
`DELETE /policies/:id`	`policies:write`	Archive; 204, no response body
`POST /policies/:id/restore`	`policies:write`	No body; returns `{ "restored": true }`

Create and update responses include the draft’s id, name, digest, and revision. When editing, fetch the current revision and preserve metadata.name. On 409, refresh and show the differences to the human. Publication separately approves the exact reviewed digest and creates an immutable version. The engine’s canonical digest is authoritative; do not hash raw YAML yourself. Do not publish silently from a sync agent.

For a worked authoring example, see turning terms of use into an Antaeus content policy, including clause mapping, exceptions, a downloadable policy and an API request.

History and support

Usage & requests displays the last 30 days and latest 100 requests, with lookup by X-Request-Id. Request metadata and structured Decisions are retained for 90 days; raw evaluation inputs and inline policy text are not persisted in that log. Managed policy source and its synthetic example are stored when saved. Inputs and policies still pass to the evaluation provider; see privacy before submitting data.

For integration help, contact hello@antaeus.io with the request ID and error code, without API keys or raw sensitive input. The generic coding-agent prompt is available; the dashboard supplies instructions configured for your published policy. These docs describe the production beta as of 14 October 2026. For credential-free local evaluation, use the separate open-source quickstart.