API Reference

REST · JSON · Bearer

HTTP API Reference

Every Patchr surface is available over HTTP. This reference covers authentication, orchestration, all seven domains, events, schemas, and the sandbox.

Base URL

https://api.patchr.co

All requests go to this base. Public routes work without a token. Protected routes require Authorization: Bearer <token>.

Authentication

Create an API token from the dashboard. Pass it as a bearer token on every request that requires authentication.

Authorization: Bearer pk_live_your_token_here

Rate limits

Builder plan: 500 orchestration runs/month. Team plan: unlimited. Burst limit: 60 requests/minute per token. Responses include X-RateLimit-Remaining.

Jump to:Authentication Orchestrator Workflow Templates Resolve Proof & Receipts Hunt Bridge Proxy Pay Tasks Events Schemas & Protocol Sandbox

Authentication

All protected routes require a bearer token in the Authorization header. Tokens are scoped to a builder account and can be rotated from the dashboard.

GET/healthzPublic

Health check

Returns API health, version, and contract counts. No authentication required.

Example request

curl https://api.patchr.co/healthz

Response shape

{ "ok": true, "version": "...", "contractCount": 178 }

GET/v1/manifestPublic

Integration manifest

Returns the public integration manifest: available domains, transports, schema refs, and version info. Read this before building.

Example request

curl https://api.patchr.co/v1/manifest

Response shape

{ "domains": ["hunt","resolve","bridge","proxy","pay"], "transports": ["http","mcp","a2a"], "version": "..." }

GET/v1/protocol-mapPublic

Protocol map

Returns the full route map: every public endpoint, its domain, method, auth requirement, and schema refs.

Example request

curl https://api.patchr.co/v1/protocol-map

POST/v1/handshakeBearer token

Integration handshake

Validate that your client is compatible with the requested domain surfaces before registering or delegating.

Request body

domainsstring[]Domains your integration will use, e.g. ["resolve","proxy"].required

clientIdstringOptional stable identifier for your integration.

transportstring"http" | "mcp" | "a2a". Defaults to "http".

Example request

curl -X POST https://api.patchr.co/v1/handshake \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domains":["resolve","proxy"]}'

Response shape

{ "ok": true, "compatible": true, "domains": [...], "contractRef": "..." }

Orchestrator

Core

The orchestrator is the unified entry point. It routes requests across Hunt, Resolve, Bridge, Proxy, and Pay based on NLP classification or an explicit domainRoute.

POST/v1/orchestrator/runBearer token

Run orchestration

Submit a natural-language request or structured payload. The orchestrator classifies intent, activates the relevant domains, and returns a proof card with evidence status, confidence, open questions, and recommended next action.

Request body

requeststringNatural-language request or goal, e.g. "Buy me an iPhone 7 under $550".required

conversationIdstringStable ID to group follow-up turns into one conversation thread.

domainRoutestring[]Force a specific domain sequence, e.g. ["resolve","proxy"]. Skips NLP routing.

clientIdstringCalling client or user identifier.

metadataobjectArbitrary key/value context forwarded to every domain handler.

streambooleanSet true to receive domain events as SSE before the final response.

actionstringResume action for follow-up turns: "buy" | "contact" | "proxyOutcome".

itemIdstringCandidate ID selected by the user in a NEEDS_INPUT(choice) response.

Example request

curl -X POST https://api.patchr.co/v1/orchestrator/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Audit disputed claim #4821",
    "conversationId": "conv_abc123",
    "domainRoute": ["resolve","proxy"]
  }'

Response shape

{
  "ok": true,
  "status": "ready" | "NEEDS_INPUT" | "awaitingProxy",
  "route": ["resolve","proxy"],
  "results": { "resolve": {...}, "proxy": {...} },
  "proofCard": { "evidenceStatus": "sourceBound", "confidence": 0.87, ... },
  "agentConversation": ["[Resolve] Checked evidence...", ...],
  "trace": [...]
}

Workflow Templates

Pre-packaged domain sequences for common use cases. Each template returns evidence status, confidence, open questions, and a proof card.

GET/v1/workflows/templatesPublic

List templates

Returns all published workflow templates with their IDs, domains, descriptions, and schema refs.

Example request

curl https://api.patchr.co/v1/workflows/templates

POST/v1/workflows/templates/{templateId}/runBearer token

Run a template

Execute a named template. Returns the same shape as /v1/orchestrator/run but with template-specific defaults applied.

Request body

templateIdstringe.g. "auditDisputedClaim" | "findBestFit" | "coordinateHumanProcess".required

requeststringOverride the default request prompt.

conversationIdstringStable conversation ID for multi-turn flows.

metadataobjectContext forwarded to every domain handler.

Example request

curl -X POST https://api.patchr.co/v1/workflows/templates/auditDisputedClaim/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"request":"Review claim #4821","conversationId":"conv_abc"}'

Resolve

Audit, contradiction detection, evidence mapping, and reviewable case records.

POST/v1/resolve/scamTriageBearer token

Run scam triage

Submit a claim and optional evidence references. Returns risk classification, evidence map, contradictions, missing evidence, confidence, recommended restraint, and next action.

Request body

claimstringThe claim text to audit.required

documentsstring[]Evidence references or attachment IDs.

taskIdstringAttach to an existing task.

Example request

curl -X POST https://api.patchr.co/v1/resolve/scamTriage \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"claim":"Offer seems fake, documents don'"'"'t match","documents":["att_123"]}'

Response shape

{
  "triage": {
    "risk": { "label": "scamTriage", "severity": "critical" },
    "evidenceMap": [...],
    "contradictions": [...],
    "confidence": 0.74,
    "recommendedRestraint": "escalateBeforeActing",
    "nextAction": "requestHumanReview"
  }
}

Proof & Receipts

First-class proof surfaces — proof cards, proof packs, and payment receipts — with stable cite refs for cross-system portability and Decionis-compatible decision ledger export.

GET/v1/audit/proofCards/{cardId}Bearer token

Fetch proof card

Retrieve a proof card by ID. Proof cards are the portable, citable output of every completed workflow. Each card carries evidenceStatus, confidence, openQuestions, recommendedRestraint, and a stable citeRef for external ledger import.

Path / query parameters

cardIdstringProof card identifier, e.g. card_abc123.required

Example request

curl https://api.patchr.co/v1/audit/proofCards/card_abc123 \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

Response shape

{
  "cardId": "card_abc123",
  "kind": "proofCard",
  "evidenceStatus": "sourceBound",
  "confidence": 0.91,
  "openQuestions": [],
  "recommendedRestraint": "proceedSafely",
  "cite": "patchr:proofCard:card_abc123#v1",
  "citeRef": "patchr:decisionLog:decision_q3_001#v1"
}

GET/v1/audit/proofPacks/{packId}Bearer token

Fetch proof pack

Retrieve a saved proof pack by ID. Proof packs are sealed audit containers: source snapshots, evidence hashes, contradiction records, decision logs, and receipts. Use for compliance export, board review, or regulator submission.

Path / query parameters

packIdstringProof pack identifier, e.g. pack_abc123.required

Example request

curl https://api.patchr.co/v1/audit/proofPacks/pack_abc123 \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

Response shape

{
  "packId": "pack_abc123",
  "status": "sealed",
  "cite": "patchr:proofPack:pack_abc123#v1",
  "sections": [
    { "kind": "evidenceMap", "itemCount": 4, "allSourceBound": true },
    { "kind": "decisionLog", "selectedPath": "...", "rejectedCount": 2 },
    { "kind": "receipts",    "receiptId": "rcpt_..." }
  ],
  "shareUrl": "https://api.patchr.co/v1/audit/proofPacks/pack_abc123"
}

GET/v1/pay/receipts/{receiptId}Bearer token

Fetch payment receipt

Retrieve a settlement receipt by ID. Receipts carry amount, vendor, proof-of-value ref, status, and a cite ref for reconciliation. Compatible with finance export and audit pack inclusion.

Path / query parameters

receiptIdstringReceipt identifier, e.g. rcpt_abc123.required

Example request

curl https://api.patchr.co/v1/pay/receipts/rcpt_abc123 \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

Response shape

{
  "receiptId": "rcpt_abc123",
  "status": "settled",
  "amount": { "amount": 480, "currency": "USD" },
  "vendorId": "vendorA",
  "povRef": "pov_vendor_verified",
  "cite": "patchr:receipt:rcpt_abc123#v1"
}

POST/v1/audit/proofCards/{cardId}/exportBearer token

Export proof card to ledger

Export a proof card into a portable decision ledger entry. Returns a ledger-compatible JSON payload with the full decision context, rejected paths, evidence refs, and a stable citeRef for import into Decionis-style governance systems.

Path / query parameters

cardIdstringProof card to export.required

Request body

formatstring"patchr/v1" (default) | "decionis/v1". Controls the export envelope shape.

includeRejectedPathsbooleanInclude pruned candidate paths and their reasons. Default true.

audiencestring"board" | "regulator" | "legal" — adjusts redaction. Default none.

Example request

curl -X POST https://api.patchr.co/v1/audit/proofCards/card_abc123/export \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"format":"decionis/v1","includeRejectedPaths":true,"audience":"regulator"}'

Response shape

{
  "ledgerEntry": {
    "format": "decionis/v1",
    "citeRef": "patchr:decisionLog:decision_q3_001#v1",
    "evidenceStatus": "sourceBound",
    "confidence": 0.91,
    "selectedOption": { ... },
    "rejectedPaths": [ ... ],
    "exportedAt": "2026-05-23T10:00:00Z"
  }
}

Hunt

Source-bound discovery across markets, local places, lead sources, and evidence candidates.

POST/v1/hunt/searchBearer token

Discovery search

Run a structured discovery search. Returns source-bound candidates ranked by eligibility, price, evidence, and user constraints.

Request body

querystringNatural-language search request.required

sourcesstring[]Limit search to specific sources, e.g. ["blocket","ebay"].

budgetobject{ maxUsd: number } spend cap for filtering.

locationstringGeographic context for local searches.

taskIdstringAttach results to an existing task.

Example request

curl -X POST https://api.patchr.co/v1/hunt/search \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"query":"iPhone 7 under $550","sources":["blocket","ebay"],"budget":{"maxUsd":550}}'

Response shape

{
  "ok": true,
  "candidates": [
    { "candidateId": "...", "title": "...", "netUsd": 480, "source": "blocket", "eligible": true }
  ],
  "sourceTelemetry": { ... }
}

POST/v1/tools/mapBearer token

Local place search

Search for local service providers via Google Places. Returns place candidates with name, address, rating, and distance.

Request body

querystringEntity + location query, e.g. "mechanic near Hisingen, Gothenburg".required

radiusKmnumberSearch radius in kilometres. Default 10.

googlePlacesApiKeystringCaller-supplied key. Omit to use the server-configured key.

Example request

curl -X POST https://api.patchr.co/v1/tools/map \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"query":"mechanic near Hisingen, Gothenburg","radiusKm":5}'

Bridge

Connector registration, preflight checks, and scoped external channel access.

GET/v1/bridge/connectorsBearer token

List connectors

Returns all registered connectors for the current client, including capability flags, status, and preflight readiness.

Example request

curl https://api.patchr.co/v1/bridge/connectors \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

POST/v1/bridge/connectorsBearer token

Register a new external connector. Connectors represent communication channels, APIs, or services that agents can route work through.

Request body

connectorIdstringStable identifier, e.g. "clientTwilioVoice".required

kindstring"custom" | "webhook" | "oauth" | "basicRef".required

capsstring[]Capability list, e.g. ["voice.call","identity.verify","consent.capture"].required

endpointstringTarget URL or bridge URI.required

credentialobject{ type, tokenRef } — tokenRef uses env: prefix for secret resolution.

scopesobject[]Fine-grained access scopes with actions, resources, and tokenRefs.

Example request

curl -X POST https://api.patchr.co/v1/bridge/connectors \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{
    "connectorId": "clientTwilioVoice",
    "kind": "custom",
    "caps": ["voice.call","identity.verify","consent.capture"],
    "endpoint": "bridge://client/twilio-voice",
    "credential": { "type": "basicRef", "tokenRef": "env:TWILIO_AUTH_TOKEN" }
  }'

POST/v1/bridge/connectors/{connectorId}/preflightBearer token

Connector preflight

Validate that a connector is operational before routing live traffic through it. Returns ok, status, and any blocking errors.

Request body

actionstringIntended action to validate, e.g. "call.create".required

resourcestringTarget resource identifier.

Example request

curl -X POST https://api.patchr.co/v1/bridge/connectors/clientTwilioVoice/preflight \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"action":"call.create","resource":"voice.call"}'

Response shape

{ "ok": true, "status": "ready", "connectorId": "clientTwilioVoice", "errors": [] }

Proxy

Human mission coordination — suspend autonomous work, collect verified outcomes, and resume with proof.

POST/v1/proxy/missionsBearer token

Create a mission

Open a human coordination mission. The orchestrator suspends until the mission receives an outcome callback with proof.

Request body

taskIdstringParent task identifier.required

kindstring"call" | "message" | "review" | "logistics".required

reasonstring"localServiceAvailability" | "identityVerificationAndConsent" | "humanReviewerNeeded".required

taskstringHuman-readable mission description.required

contextobjectMission context: selectedProvider, logisticsBrief, decisionFork.

voiceCallobject{ phone, prompt, connectorId } for voice-directed missions.

channelMsgobject{ channel, to, text, connectorId } for message-directed missions.

proofReqstring[]Required proof items, e.g. ["callTranscript","consentRecord"].

resumeobject{ conversationId, candidateId, action } resume hint for the orchestrator.

Example request

curl -X POST https://api.patchr.co/v1/proxy/missions \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{
    "taskId": "task_abc123",
    "kind": "call",
    "reason": "identityVerificationAndConsent",
    "task": "Contact Hisingen Auto Repair to confirm availability.",
    "voiceCall": { "phone": "...", "prompt": "Verify availability for...", "connectorId": "clientTwilioVoice" },
    "proofReq": ["callTranscript","consentRecord"],
    "resume": { "conversationId": "conv_abc", "action": "proxyOutcome" }
  }'

Response shape

{ "ok": true, "proxyId": "proxy_xyz", "status": "open", "mission": {...} }

POST/v1/proxy/missions/{proxyId}/outcomeBearer token

Submit mission outcome

Record the human outcome for a mission. If the reason was localServiceAvailability or identityVerificationAndConsent and status is confirmedSuccess, the provider is upgraded to verified in the local provider book.

Request body

statusstring"confirmedSuccess" | "providerUnavailable" | "failed".required

notestringHuman-written outcome summary.

availabilityobject{ status, availableAt, providerName }.

proofobjectProof artifacts collected during the mission.

Example request

curl -X POST https://api.patchr.co/v1/proxy/missions/proxy_xyz/outcome \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{
    "status": "confirmedSuccess",
    "note": "Confirmed available today at 15:00.",
    "availability": { "status": "available", "availableAt": "today 15:00", "providerName": "Hisingen Auto Repair" }
  }'

Response shape

{ "ok": true, "verifiedProvider": { "name": "...", "providerId": "...", "availability": {...} } }

GET/v1/proxy/missions/{proxyId}Bearer token

Get mission

Fetch a proxy mission by ID including status, context, outcome, and proof artifacts.

Example request

curl https://api.patchr.co/v1/proxy/missions/proxy_xyz \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

Pay

Payment mandates, settlement requests, escrow, receipts, and proof-of-value.

POST/v1/pay/mandatesBearer token

Create a mandate

Issue a payment intent mandate with spend constraints, allowed vendors, and resolve rules. The mandate gates settlement — the pay domain will not execute without it.

Request body

taskIdstringParent task for this mandate.required

constraintsobject{ maxSpend: { amount, currency }, allowedVendors, resolveRules }.required

issuerobject{ entityId, publicKey }.

Example request

curl -X POST https://api.patchr.co/v1/pay/mandates \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{
    "taskId": "task_abc123",
    "constraints": {
      "maxSpend": { "amount": 550, "currency": "USD" },
      "resolveRules": ["inventoryVerified","hiddenFeeClear"]
    }
  }'

POST/v1/pay/settleBearer token

Execute settlement

Attempt settlement against a validated mandate. Returns a receipt with status, amount, proof-of-value ref, and any errors.

Request body

mandateIdstringMandate to settle against.required

taskIdstringParent task.required

vendorIdstringWinning vendor from the Resolve decision tree.required

amountnumberSettlement amount in USD.required

povRefstringProof-of-value reference from the vendor.

Example request

curl -X POST https://api.patchr.co/v1/pay/settle \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"mandateId":"mandate_abc","taskId":"task_abc","vendorId":"vendorA","amount":480}'

Response shape

{ "ok": true, "receipt": { "receiptId": "...", "status": "settled", "amount": 480 } }

Tasks

Create, track, and manage protocol task lifecycle across all domains.

POST/v1/tasksBearer token

Create task

Create an auditable task record. Tasks are the durable unit of work that spans domain handoffs.

Request body

domainstringStarting domain: "hunt" | "resolve" | "bridge" | "proxy" | "pay".required

inDataobjectInitial task input data.required

userIdstringRequesting user or agent ID.

channelstringOriginating channel: "api" | "mcp" | "sdk" | "sandbox".

Example request

curl -X POST https://api.patchr.co/v1/tasks \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"domain":"resolve","inData":{"claim":"Audit this dispute"},"channel":"api"}'

GET/v1/tasks/{taskId}Bearer token

Get task

Fetch task state, status, domain, input/output data, and audit trail.

Example request

curl https://api.patchr.co/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

Events

Subscribe to domain events, delivery status, and integration callbacks.

POST/v1/events/subscriptionsBearer token

Create subscription

Subscribe a webhook endpoint to one or more event types. Patchr will POST signed event payloads to your endpoint.

Request body

endpointstringHTTPS URL to deliver events to.required

eventsstring[]Event type list, e.g. ["task.completed","proxy.outcome","pay.settled"].required

secretstringHMAC signing secret for payload verification.

Example request

curl -X POST https://api.patchr.co/v1/events/subscriptions \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"endpoint":"https://yourapp.com/hooks/patchr","events":["task.completed","proxy.outcome"]}'

GET/v1/events/subscriptionsBearer token

List subscriptions

Returns all active event subscriptions for the current client.

Example request

curl https://api.patchr.co/v1/events/subscriptions \
  -H "Authorization: Bearer $PATCHR_API_TOKEN"

Schemas & Protocol

Machine-readable contract surfaces for validation, discovery, and agent-readable policy.

GET/v1/schemasPublic

Schema catalog

Returns all published JSON Schemas keyed by schema ID. Use these to validate request and response payloads before sending.

Example request

curl https://api.patchr.co/v1/schemas

GET/openapi.jsonPublic

OpenAPI spec

Full OpenAPI 3.1 specification for all Patchr HTTP routes. Compatible with Swagger UI, Redoc, and code-generation tools.

Example request

curl https://api.patchr.co/openapi.json

GET/v1/security/policyPublic

Agent-readable policy map

Returns the machine-readable policy map: allowed capabilities per domain, mandate requirements, and preflight rules.

Example request

curl https://api.patchr.co/v1/security/policy

POST/v1/security/policy/evaluateBearer token

Evaluate policy

Test whether a specific action is permitted under the current policy for a given domain and connector.

Request body

domainstringDomain to check: "bridge" | "proxy" | "pay".required

actionstringAction to evaluate, e.g. "call.create".required

connectorIdstringConnector ID for bridge/proxy actions.

Example request

curl -X POST https://api.patchr.co/v1/security/policy/evaluate \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"domain":"bridge","action":"voice.call","connectorId":"clientTwilioVoice"}'

Sandbox

Deterministic benchmarks and orchestrator playgrounds — no side effects, no production API key required.

POST/v1/sandbox/midnight-arbitragePublic

Midnight Arbitrage benchmark

Run the deterministic HUNT → RESOLVE → PAY benchmark. Returns vendor telemetry, decision tree, mandate, receipt, and full trace. Supports chaos injection.

Request body

chaosstring"" | "latency" | "modelError" | "unauthorizedSpend" | "freeze". Default empty (happy path).

Example request

curl -X POST https://api.patchr.co/v1/sandbox/midnight-arbitrage \
  -d '{"chaos":""}'

Response shape

{
  "ok": true, "status": "settled", "chaos": "",
  "receipt": { "receiptId": "...", "status": "settled", "amount": 80 },
  "decisionTree": { "selected": "vendorA", "paths": [...] },
  "trace": [...]
}

POST/v1/orchestrator/runBearer token

Live orchestration (sandbox mode)

Run the full orchestrator against the sandbox. Use conversationId "sandbox_*" and omit sensitive inputs.

Request body

requeststringAny natural-language request.required

conversationIdstringUse a sandbox-prefixed ID to avoid mixing with production conversations.

Example request

curl -X POST https://api.patchr.co/v1/orchestrator/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{"request":"Find me an iPhone 7 under $550","conversationId":"sandbox_test_1"}'

Error codes

All error responses use the same envelope: { "ok": false, "error": "errorCode", ... }. HTTP status follows standard semantics.

400invalidPayloadRequest body failed schema validation.

401unauthorizedMissing or expired bearer token.

403forbiddenToken lacks the required scope for this route.

404notFoundResource (task, mission, connector) not found.

409conflictDuplicate resource creation or state conflict.

422policyViolationAction blocked by mandate or connector policy.

429rateLimitExceededToo many requests — check X-RateLimit-Remaining.

500internalErrorUnexpected server error. Retry with exponential backoff.

Prefer an SDK?

Python and Node.js SDKs wrap every route shown here.

SDKs handle token management, retries, and response parsing. Start there if you don't need direct HTTP control.

SDK Quickstart Try in Sandbox