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.

Proof: own the source and inspect citations

Create an immutable snapshot with POST /v1/proof/sources and an idempotency key:

{
  "title": "My source",
  "version": "1",
  "authority": "Source author",
  "language": "en",
  "rights": {
    "ingest_allowed": true,
    "return_excerpts": false,
    "basis": "A generated example I own"
  },
  "passages": [
    {"locator": "section 1", "text": "Every bird flies."},
    {"locator": "section 2", "text": "Every dog sleeps."}
  ]
}

The caller must actually have those rights; the fields are assertions, not a rights check. Use unique locators and up to 100 passages, each at most 4,000 characters. Create POST /v1/proof/jobs with an idempotency key and {source_id, statement, language: "en", budget}. For example, a bounded budget is {max_seconds: 70, max_passages: 4, max_reading_combinations: 8}. Read/cancel at /v1/proof/jobs/{job_id} and /v1/proof/jobs/{job_id}/cancel.

Render p7y.proof.result/0.1 steps, complete statements, source citations, inference labels, predecessor steps and limits. proved is relative to the chosen source; it does not establish the source's truth. unresolved is not disproof. Missing excerpt rights retain the citation locator and report rights_restricted. Retrieval and reasoning are bounded and do not promise exhaustive source recall. Changing source text requires a new snapshot; an old result applies to its old snapshot. DELETE /v1/proof/sources/{source_id} deletes the source and its jobs.

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.