API Reference

Source: docs/06-api-reference.md

API Reference

This is the public runtime API used by the portal and SDKs. It is deterministic by design: identical inputs yield identical boundary maps under the same lens + ruleset.

Base URL

Hosted gateway: https://api.practice-wallet.com

Hosted routes are available under /api/*. If you self-host the runtime service, use the bare routes (/interpret, /replay, /diff, etc).

Authentication

Use a server-side API key.
Send as: Authorization: Bearer <api_key>
Rate limits apply per key. Exceeding limits returns 429 rate_limited.

Supported values

Lens:

literal_technical_reader@v0.1

Ruleset:

facet_a_inference_mechanics@v0.1

Artifact types:

MODEL_CARD, EVAL_SUMMARY, CAPABILITY_DISCLOSURE, FREE_TEXT

POST /interpret

Interpret a text artifact using a fixed lens and ruleset.

Required:

artifact_text (string)
artifact_type
lens (lens_id, lens_version)
ruleset (ruleset_id, ruleset_version)

Optional:

artifact_metadata (object)
producer (provenance, vendor/model, context)
analytics_policy (currently allow_vendor_aggregation: false only)
eligibility_mode (standard or labs_forward_looking)
assumption_records (advanced: supply your own records instead of inference)

Example:


{

  "artifact_text": "We aim to respond within 72 hours.",

  "artifact_type": "FREE_TEXT",

  "lens": { "lens_id": "literal_technical_reader", "lens_version": "v0.1" },

  "ruleset": { "ruleset_id": "facet_a_inference_mechanics", "ruleset_version": "v0.1" }

}

Response (shape):


{

  "analysis_run_id": "uuid",

  "artifact_hash": "sha256",

  "lens": { "lens_id": "literal_technical_reader", "lens_version": "v0.1" },

  "ruleset": { "ruleset_id": "facet_a_inference_mechanics", "ruleset_version": "v0.1" },

  "producer": { "...": "..." },

  "producer_hash": "sha256",

  "started_at": "ISO-8601",

  "completed_at": "ISO-8601",

  "assumption_records": [

    {

      "id": "uuid",

      "analysis_run_id": "uuid",

      "artifact_hash": "sha256",

      "artifact_type": "FREE_TEXT",

      "inferred_claim": "string",

      "source_excerpt": "string",

      "boundary_map": { "...": "..." },

      "human_explanation": { "...": "..." }

    }

  ]

}

POST /replay

Replay a prior interpretation by signature (artifact hash + lens + ruleset).

Request:


{

  "artifact_hash": "sha256",

  "artifact_type": "FREE_TEXT",

  "lens": { "lens_id": "literal_technical_reader", "lens_version": "v0.1" },

  "ruleset": { "ruleset_id": "facet_a_inference_mechanics", "ruleset_version": "v0.1" }

}

Response is the same shape as /interpret.

POST /diff

Compute a deterministic diff between two runs under the same lens + ruleset.

Request:


{

  "artifact_identifier": "terms-of-service",

  "analysis_run_id_a": "uuid",

  "analysis_run_id_b": "uuid"

}

Response (shape):


{

  "drift_id": "uuid",

  "added": [ { "...": "assumption record" } ],

  "removed": [ { "...": "assumption record" } ],

  "unchanged": [ { "...": "assumption record" } ],

  "net_change": 3

}

GET /assumptions/:analysis_run_id

Fetch assumption records for a prior run.

Response:


{ "assumption_records": [ { "...": "assumption record" } ] }

GET /history/:artifact_identifier

List diff history (drift) entries for an artifact identifier.

Response:


{

  "history": [ { "drift_id": "uuid", "created_at": "ISO-8601", "net_change": 1 } ],

  "limit": 50,

  "offset": 0

}

Error semantics

400 invalid_request (schema or validation errors)
400 unsupported_lens / unsupported_ruleset / unsupported_artifact_type
401 unauthorized
404 not found (run or record not found)
409 decision_exists (curation only)
429 rate_limited
500 server_error