REST API

Felspar's REST routes - authentication, the agent routes, authoring and review routes, the decision result, and request formats.

Base URL: https://api.felspar.ai. All routes are versioned under /v0.

This page is written by hand from the service’s routes and contracts. A generated reference from a reviewed OpenAPI contract is coming and will replace it.

Authentication

Every request checks the credential, the caller’s current membership and grants. There is no cross-origin browser access. Responses are never cached.

Request bodies

• JSON bodies up to 2 MiB.
• application/x.felspar-content-parts bodies up to 4 MiB. This compact format, used by the SDK and the web app, sends repeated text once; Felspar verifies every part against its fingerprint before use.

Agent routes

These are the routes a registered agent uses. An agent can call them only for jobs it is registered for.

A person calling the job routes gets the job’s newest release.

Release-specific routes

To work against one exact release:

Decision request

A fictional support desk’s triage-ticket job, whose subject is a ticket with one related customer:

{
  "mode": "facts",
  "executionId": "a-new-uuid",
  "jobId": "triage-ticket",
  "entityId": "48213",
  "related": { "customer": "cus-9f2" },
  "expectedReleaseDigest": "sha256:... (optional on job routes)",
  "facts": {
    "topic": {
      "text": "I was charged twice for the October invoice.",
      "source": { "class": "ticket", "id": "48213", "locator": "48213#message-1", "observedAt": "2026-10-21T09:00:00Z" }
    },
    "premium": {
      "text": "Plan: Premium (yearly), account manager: assigned",
      "source": { "class": "account", "id": "cus-9f2", "observedAt": "2026-10-20T00:00:00Z" }
    }
  }
}

• entityId: the case’s ID, as the brief’s identity.send and subject.send say. Felspar normalizes it by the subject’s match rule (trimmed; lowercased too for case-insensitive) before it counts attempts, keeps history or writes a receipt. Required when the job uses the record’s own ID (provided, and every job released before identity modes). Leave it out for a fields or content job, and on the first decision of an issued job; afterwards send the case.id Felspar returned. See identity modes.

• identity: only for a fields job, each identity field’s value by name, such as { "email": "sam@example.com", "requisition": "REQ-114" }. Felspar derives the case ID from them.

• related: only for questions about a related record. Each relationship’s record ID, or a list of IDs for a many relationship; then each excerpt for that question names its record in about. At most 16 related IDs.

• executionId: unique per decision. Resending the same ID with the same body returns the original result and is never decided twice. A different body with a used ID is refused (execution_id_reused). A request whose earlier attempt is still running or unknown is never re-run automatically.

• facts: per question, one excerpt, a list of up to 3, or (number and date questions only) a typed { value, source }. A typed value from a CRM looks like { "value": 1200, "source": { "class": "crm-record", "id": "acct-881", "observedAt": "..." } }. source may also carry excerpt, the exact words that state the value.

• expectedReleaseDigest: optional on /v0/jobs/{job}/decisions; if left out, the decision is bound to the release Felspar chose, which the result records. Required on /v0/releases/{id}/jobs.

Decision result

{
  "status": "ready",
  "reason": null,
  "result": {
    "executionId": "a-new-uuid",
    "executionObjectId": "execution-...",
    "resultId": "result-...",
    "releaseId": "release-...",
    "releaseDigest": "sha256:...",
    "evaluationTime": "2026-10-21T09:00:03.120Z",
    "evidenceMode": "felspar-interpreted",
    "outcome": "billing",
    "scoring": null,
    "context": null,
    "subject": { "type": "ticket", "id": "48213", "related": [{ "relationship": "customer", "subject": "customer", "id": "cus-9f2", "questions": ["premium"] }] },
    "receipt": { "receiptDigest": "sha256:...", "...": "..." },
    "explanation": { "...": "see below" },
    "diagnostics": [],
    "interpretation": { "...": "how each excerpt was read", "judgmentsDigest": "sha256:...", "modelCalls": 3 }
  }
}

The next step for a decided outcome is in the brief’s outcomes[].nextStep.

A wrong or missing case ID is refused with one of the identity refusals. A caller may open at most 200 new issued cases per job in any 24 hours (issued_case_limit).

Verify request and result

{ "receipt": { "...": "result.receipt" }, "expectedReceiptDigest": "sha256:...", "deliveredCapsule": null }

Result: { "authority": "unapproved", "status": "reproduced" | "mismatch", "mismatches": [], "decided": { "jobId", "entityId", "releaseId", "outcome", "case", "subject", "escalation" } }. case ({ id, mode }) is recomputed from the retained request by the release’s identity mode; subject ({ type, related }) and escalation ({ id, trigger }) are re-derived from the release and the replayed outcome. Each appears when the release declares it. See Verify receipts.

Authoring and review routes

For signed-in people. The authoring MCP tools call these same routes.

Approval and release are used by the web app’s review pages. An MCP sign-in and agent keys can never call them.

Errors

Every deliberate refusal is JSON:

{
  "error": "too_many_excerpts",
  "path": ["facts", "topic"],
  "issues": [
    { "code": "too_many_excerpts", "path": ["facts", "topic"], "fix": "Send at most 3 excerpts per question." },
    { "code": "unknown_question", "path": ["facts", "severity"], "fix": "This question is not in the released job. Use the question keys from describe." }
  ]
}

Every mistake in a request is reported together, so you can fix them all in one pass. Refusals name codes and paths, never your submitted values or source text. Anything not deliberately described is 403 operation_unavailable. See Refusal codes.

Health

GET /health answers when the service is running. It says nothing about your workspace.