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.

Meaning: interpret, clarify and review

curl --fail-with-body https://api.p7y.ai/v1/meaning/jobs \
  -H "Authorization: Bearer $P7Y_ID_TOKEN" \
  -H "Idempotency-Key: $P7Y_REQUEST_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"language":"en","kind":"prose","text":"Birds fly. Dogs sleep."}'

Read GET /v1/meaning/jobs/{job_id} until the job is completed, declined, failed or cancelled. Cancel through POST /v1/meaning/jobs/{job_id}/cancel. Preserve meaning/0.1 result bytes, all readings, plain-language definitions, quantities, polarity, conditions, exceptions, source spans and limits. Source spans use Unicode code-point offsets. Review every statement against the submitted source, including anything marked not_restated. Independent supported documents are available; unsupported references and incomplete coverage remain explicit limitations.

An explicit result still needs author review. An ambiguous result must not be silently reduced to the first reading. When the checked clarification offers yes/no, call POST /v1/meaning/jobs/{job_id}/clarify with a new idempotency key and {question_id, answer, source_sha256, result_sha256}. The result hash uses the complete delivered result's canonical JSON. This free answer creates an immutable continuation job; the original remains unchanged. Follow the returned job and review every surviving complete restatement. If the API offers whole-reading selection instead, review those alternatives. Revise the source if none matches.

Acceptance is a separate action: POST /v1/meaning/jobs/{job_id}/accept with an idempotency key, source/result hashes, and reading_id for an ambiguous result. Include previous_acceptance_id when superseding a previous accepted revision. Only submit it after the author deliberately accepts the full reading and limits. Read GET /v1/meaning/acceptances/{acceptance_id} for current status. Source or engine changes may require a new interpretation and acceptance. Acceptance does not qualify the engine or grant permission to execute a tool.

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.