MagWorksManaged Intelligence

The product

Our API

In plain language

A client's own software can call their Solution directly. The contract is small and stable: run a Capability and get the result, or stream it; poll a run that paused for review; read and propose relationship memory; and read the sanitised evidence for any of your own runs. The credential never leaves the client's server, isolation is per relationship, and refusals are typed and safe to show.

The mechanism

Addressing (RUN-1). POST https://<gateway-host>/v1/capabilities/<slug>/runs on a registered channel. A Solution is not directly invocable; a client entitled through a Solution invokes its constituent Capabilities.

Required headers (RUN-2). Authorization: Bearer <credentialId>:<secret>; Idempotency-Key: <fresh uuid per logical request>; Content-Type: application/json. The body carries input matching the Capability's declared input contract.

Responses (RUN-4). 200 with { requestId, status: "completed", output, completedAt }; 202 with { requestId, status: "waiting", waitType: "human_review" | "processing", runId }; or a customer-safe error { requestId, errorCode, errorMessage }.

Error taxonomy (RUN-5). 400 malformed_request; 401 missing_api_key, invalid_api_key, inactive_credential; 402 subscription_inactive; 403 capability_access_grant_missing, capability_access_grant_inactive, forbidden_no_entitlement, forbidden_subscription_canceled; 404 capability_access_not_found, capability_access_inactive; 409 idempotency_conflict; 429 rate_limit_exceeded; 503 endpoint_not_provisioned, capability_temporary_failure. Substrate-internal codes never appear in a customer response.

The gate chain. The access gateway is a thin edge adapter: parse → authenticate (hashed credentials) → access → grant → idempotency → quota, then dispatch. Quota is per credential (100 requests per minute and 2,000 per day, shared across surfaces) and enforced by a store that fails closed. Metering is failure-isolated — a metering fault never blocks a customer invocation (I-16).

The v1 surface.

Method Path Purpose
POST /v1/capabilities/{slug}/runs buffered run, Idempotency-Key required
GET /v1/capabilities/{slug}/runs/{runId} poll a waiting run
POST /v1/capabilities/{slug}/stream streamed run over SSE: event: chunk | final | error
POST /v1/relationships/{rid}/memory/proposals submit memory proposals; the platform lifecycle engine decides
GET /v1/relationships/{rid}/memory list current memory (?include=superseded for history)
DELETE /v1/relationships/{rid}/memory erase all memory for a relationship — tombstones + ledgered disclosure
GET /v1/capabilities/{slug}/runs/{runId}/evidence sanitised run evidence, the caller's own runs only

Streamed runs are attributed to the Solution and produce the same completion event and cost truth as buffered runs; grounding on the streamed lane resolves fail-closed like the buffered lane.

The client boundary. Browser → the client's own backend → our API. The credential lives in the client's server-side secret store; no CORS is configured, so browser-direct calls fail by construction. Per-user isolation is a derived relationship id. Rotation issues a new secret with a short grace window for the prior one; the client re-reads its secret store, with no code change.

Solution webhooks. A Solution may declare a webhookUrl; the dispatcher signs each delivery (X-Mag-Signature, HMAC over the body, re-minted per attempt), retries endpoint failures through EventBridge into a dead-letter queue with an alarm, drops only malformed envelopes (a retry cannot fix shape), and delivers at least once — consumers dedupe on (runId, eventType).

Proven in production. Buffered and streamed capabilities, relationship memory and run evidence are all exercised over this exact contract by live clients; the OpenAPI document that describes it is captured production truth, not a design.

Design notes

  • Why an idempotency key is required, not optional. Exactly-once logical execution at the edge of our API is the same primitive the substrate uses everywhere (ADR-0015); a client retry can never double-run a Capability.
  • Why evidence is a customer-safe projection (ADR-0038). The platform already recorded rich per-run truth; what was missing was an interpretation layer that answers "why did it answer this way" without exposing substrate vocabulary.
  • Why the credential never reaches a browser. A clean client boundary is what makes our API a product rather than a shared key.

Sources

  • matterandgas-com/docs/architecture/runtime-specification.md (RUN-1…5).
  • the OpenAPI description of the v1 contract (matterandgas-com/docs/).
  • matterandgas-com/amplify/functions/mag-capability-access-gateway/, mag-capability-stream-gateway/, solution-webhook-dispatcher/.