External product API quickstart

Meaning, Proof and Action use the shared API at https://api.p7y.ai in production and https://parsimony-api-dev-chirbppamq-uc.a.run.app in dev. Keep a workflow in one environment. GET /v1/products lists the serving release, product modes and service-specific tutorial addresses. Current contracts are development fragments. Action policies start in shadow mode, where every decision is no.

Use the signed-in person's Firebase ID token in Authorization: Bearer …. Keep credentials private. Each person can read only their owned workspace records. Browser workspaces obtain the token through the account facade. An internal role is required for Console and Logic; those services are separate from the external product API documented here. Their trees and SHEAF artifacts are not external Meaning, Proof or Action results.

Use a fresh Idempotency-Key for each new command. Preserve that key and the exact body when manually retrying the same command after an uncertain response; a changed body with the same key returns 409. HTTP failures are errors, not product results. Preserve the user's input and show the returned error. Do not infer a successful outcome or automatically repeat mutations.

Action: decisions, execution tokens and recorded evidence

Start with an accepted Meaning interpretation. POST /v1/policies requires an idempotency key, acceptance_id, an explicitly reviewed binding and its binding_sha256 using RFC 8785 JSON Canonicalization Scheme (JCS). A supported binding is:

{
  "tool": "archive",
  "grantor_kind": "manager",
  "arguments": {"record": {"type": "identifier", "values": []}}
}

The compiler supports a narrow set of accepted unconditional universal rules, including supported independent policy documents. It rejects unsupported rules rather than dropping them. Customer rule/SOP/control/risk labels are optional customer assertions. They do not establish compliance or assess risk.

POST /v1/action-gate/decisions accepts {policy_id, call, max_explored, max_depth}. A call contains tool, arguments, resources and context; context facts are caller assertions. A new policy is in shadow mode: every public decision is no, even when shadow_outcome.decision is yes, and shadow results are diagnostics, never execution permission.

POST /v1/policies/{policy_id}/activate succeeds only when a registered held-out qualification run covers the policy's rule shape on the serving release; otherwise it returns qualification_required. Any release change returns active policies to shadow. An active policy's decision carries mode: "active", its real decision and reason_code, and qualification: "registered/<run hash>". On yes it also carries token: a signed, single-use execution token that expires after 300 seconds. The executing tool redeems it once with POST /v1/action-gate/tokens/consume and {"token": …}, which appends an audit row; a second use returns 409 token_consumed. A token proves the exact call was permitted by that policy at that time, not that it was executed.

Read current status at GET /v1/policies/{policy_id} and revoke through POST /v1/policies/{policy_id}/revoke. Stored inventory status is not admission.

Owned evidence is available at GET /v1/action-gate/decisions/{decision_id}/evidence and bounded period/policy exports at GET /v1/action-gate/evidence. Keep the flattened JWS bytes exactly. Verify Ed25519 signatures offline against separately trusted environment keys from /.well-known/jwks.json. The browser displays the package and does not verify it. A signature attests issuer and integrity, not business facts or semantic correctness. Display exactly the accepted statements included by the evidence contract; do not infer missing document rules. Historical compatibility and full multi-rule statement export are tracked in parsimony_api#198.

GET /v1/action-gate/coverage reports bounded retained policy/tool coverage. Its optional from/to UTC interval is half-open and at most 31 days; complete: false means incomplete history. POST /v1/action-gate/activity with an idempotency key and {tool, gate_decision_id: null} appends a body-free execution assertion. Submitting that report does not run a tool or verify that execution occurred. Unreported activity is unknown.

Cost and retention

Meaning and Proof settle measured provider cost plus the approved 3% markup. Deterministic policy compilation/evaluation and clarification answers add no invented provider charge. Show a cost only when the API supplies measured billing data. Money remains integer microdollars on the wire; divide by 1,000,000 for presentation. Product token pricing is separate from the Console word meter.

Jobs generally retain results for 30 days; Proof sources and Action records use 90-day retention. Read errors are authoritative even before asynchronous cleanup. Evidence and coverage cannot reconstruct expired or unreported records.

Authoritative contracts and limits: Meaning API, Proof API, Action API. The browser tutorials at each service's /tutorial/ use the serving API's versioned catalogs. Live engineering fixtures do not establish held-out linguistic quality, policy accuracy, legal conclusions or general product qualification.