HTTP API - Pactmark

Compatibility: Pactmark 0.1.x. The OpenAPI document is runtime-derived — treat it as the signature source rather than copying request fields into unrelated documentation.

Mounting the handler

import { createAgentFetchHandler, createOpenApiDocument } from "@pactmark/http";

const handler = createAgentFetchHandler({
  basePath: "/v1",
  runtime,
  authenticate: async (request) => resolvePrincipalAndTenant(request),
});

const openApi = createOpenApiDocument({ runtime, basePath: "/v1" });

Routes

Operational

Method	Path	Purpose
`GET`	`/healthz`	Is the process alive?
`GET`	`/readyz`	Can it satisfy the requested profile right now?

Readiness fails closed. A memory-backed runtime asked for a production profile returns not-ready.

Runs

Method	Path	Operation
`POST`	`/v1/runs`	`startRun`
`GET`	`/v1/runs/{runId}`	`getRun`
`POST`	`/v1/runs/{runId}/resume`	`resumeRun`
`POST`	`/v1/runs/{runId}/cancel`	`cancelRun`
`GET`	`/v1/runs/{runId}/events`	`streamEvents` (SSE)

Human interaction

Method	Path	Operation
`POST`	`/v1/runs/{runId}/inputs/{requestId}`	`submitInput`
`POST`	`/v1/runs/{runId}/decisions/{decisionId}/challenge`	`issueDecisionChallenge`
`POST`	`/v1/runs/{runId}/decisions/{decisionId}`	`submitDecision`

Effects

Method	Path	Operation
`POST`	`/v1/runs/{runId}/effects/{effectId}/reconcile`	`reconcileEffect`
`POST`	`/v1/runs/{runId}/effects/{effectId}/compensate`	`requestCompensation`

Output

Method	Path	Operation
`GET`	`/v1/runs/{runId}/artifacts/{artifactId}`	`getArtifact`
`GET`	`/v1/runs/{runId}/artifacts/{artifactId}/verification`	`getVerification`
`GET`	`/v1/runs/{runId}/evidence`	`getEvidence`

Starting a run

POST /v1/runs
Content-Type: application/json
Authorization: Bearer …
Idempotency-Key: cmd_01J8…

{
  "agent": { "id": "support-refund-agent", "version": "2.1.0" },
  "goal": "Assess a refund for order ORD-88213.",
  "input": { "orderId": "ORD-88213" },
  "context": { "roleFamily": "customer_support", "workflowId": "refund-v2", "riskClass": "high" },
  "workMode": "augment",
  "autonomyMode": "delegate_review",
  "decisionOwner": { "mode": "registered_role", "role": "refund_approver" },
  "purpose": { "code": "customer_service", "registryVersion": "support@3" },
  "dataClass": "confidential",
  "retention": { "mode": "session" },
  "requestedCapabilities": ["orders:read", "payments:refund"],
  "budget": { "maxTurns": 8, "maxModelCalls": 8, "maxToolCalls": 6, "maxActiveExecutionMs": 60000 }
}

Tenant and principal are not in the body. They come from the injected authenticator.

Streaming events

Figure 1. SSE with sequence replay. Reconnect with afterSequence and the store replays from persisted events before tailing new ones.

GET /v1/runs/run_01J8…/events?afterSequence=42
Accept: text/event-stream

event: message
id: 43
data: {"eventType":"ToolCallRequested","sequence":43,"payload":{…}}

Idempotency

Map your idempotency key into the validated CommandContext. Same key with the same content returns the same result; same key with different content raises KAF_HTTP_IDEMPOTENCY_CONFLICT; an elapsed horizon raises KAF_COMMAND_IDEMPOTENCY_EXPIRED.

Errors

{
  "type": "https://pactmark.dev/errors/authorization-binding-mismatch",
  "title": "KAF_AUTHORIZATION_BINDING_MISMATCH",
  "status": 403,
  "code": "KAF_AUTHORIZATION_BINDING_MISMATCH"
}

Problem Details with a stable code. See Error reference for the full registry and retryability.

What the host configures

Authentication

An injected authenticator resolving principal, tenant, authentication strength and decision roles.

CORS and credential mode

Whatever is right for your client — the adapter does not guess.

CSRF

Required for cookie-authenticated browser clients.

Request, body and time limits

Set them. A missing body limit is a denial-of-service surface.

Admission

Per-tenant quotas and concurrency.

Disclosure level

How much a response reveals versus what goes to logs.

Treat a client disconnect as loss of transport — not cancellation, and not proof that work stopped. Inspect terminal state through the authenticated run API, and cancel explicitly when you mean it.

Streaming and clients

Building a correct client, including reconnection.

CLI

The same surfaces from a terminal.

​Mounting the handler

​Routes

​Operational

​Runs

​Human interaction

​Effects

​Output

​Starting a run

​Streaming events

​Idempotency

​Errors

​What the host configures

Authentication

CORS and credential mode

CSRF

Request, body and time limits

Admission

Disclosure level

Streaming and clients

CLI

Mounting the handler

Routes

Operational

Runs

Human interaction

Effects

Output

Starting a run

Streaming events

Idempotency

Errors

What the host configures