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:AuthenticationOrchestratorDeveloper WorkflowsWorkflow TemplatesResolveHuntBridgeProxyPayTasksEventsSchemas & ProtocolSandbox

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/profilesPublic

Create developer profile

Create a developer profile, return a starter API token, and send an email activation link. Starter tokens for unactivated email addresses are limited to 5 workflow requests.

Request body

emailstringDeveloper email address that receives the activation link.required
namestringDeveloper or team name.required
passwordstringProfile password, minimum 8 characters.required

Example request

curl -X POST https://api.patchr.co/v1/profiles \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","name":"Dev Example","password":"use-a-real-password"}'

Response shape

{ "ok": true, "token": "patchr_...", "tokenStatus": "limited", "unverifiedRequestLimit": 5, "activation": { "required": true } }
POST/v1/profiles/activatePublic

Activate starter token

Activate a starter token after the emailed activation link is opened or after a local/debug activation token is supplied.

Request body

activationTokenstringActivation token from the email link or local/debug profile response.required

Example request

curl -X POST https://api.patchr.co/v1/profiles/activate \
  -H "Content-Type: application/json" \
  -d '{"activationToken":"act_..."}'

Response shape

{ "ok": true, "status": "activated", "tokenStatus": "unlimited" }
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": "..." }
Back to top

Orchestrator

Core

The orchestrator is the unified entry point for executed work. An always-on planner routes engineering requests to the owning developer domain (environment, cicd, kubernetes, incident, migration, security, delivery) and consumer requests across Hunt, Resolve, Bridge, Proxy, and Pay — or you can force a sequence with domainRoute.

POST/v1/orchestrator/runBearer token

Run orchestration

Submit a natural-language request or structured payload. The orchestrator classifies engineering 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. "Validate this repository for production readiness".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": [...]
}
POST/v1/orchestrator/runBearer token

Stream orchestration progress

Set stream=true to receive NDJSON trace, conversation, domainStream, handoff, progress, and final events. Human-facing handoff steps include plain messages such as contacting a mechanic for availability, calling a clinic for an appointment, reaching customer service, or preparing case documents. If a domain step is quiet for 10 seconds, Patchr emits a humanized progress message so client apps can show that the run is still active.

Request body

requeststringNatural-language request or goal.required
streambooleanSet to true for application/x-ndjson streaming.required

Example request

curl -N -X POST https://api.patchr.co/v1/orchestrator/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"request":"Find a mechanic in Lekki, Lagos","stream":true}'

Response shape

{"type":"trace","event":{...}}
{"type":"handoff","phase":"proxy","name":"mission.callAvailability","status":"calling","message":"Contacting the mechanic for availability."}
{"type":"progress","status":"running","elapsedSec":10.0,"message":"I am still checking source-bound options and marketplace or map evidence."}
{"type":"final","result":{...}}
Back to top

Developer Workflows

Engineering

Software-delivery engines: configure environments, evaluate release readiness, triage clusters and incidents, gate migrations, scan for secrets, and run the delivery pipeline. Deterministic and human-gated by default; run them autonomously under an explicit mandate.

POST/v1/environment/configureBearer token

Configure environment

Analyse repository files to detect runtimes, dependencies, backing services, required secrets, and ordered setup steps. Returns a readiness verdict; no commands are executed.

Request body

filesobjectMap of {path: contents} — manifests, lockfiles, Dockerfiles, compose files, .env.example. Use filesFromLocalRepo() in the SDK.required
repoUrlstringOptional repository URL for provenance.

Example request

curl -X POST https://api.patchr.co/v1/environment/configure \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"files":{"package.json":"{...}","docker-compose.yml":"..."}}'

Response shape

{ "ok": true, "readiness": "ready|needsInput|blocked",
  "runtimes": [...], "services": [...], "secrets": [...], "setupSteps": [...] }
POST/v1/cicd/planBearer token

Plan deployment / release readiness

Evaluate release gates (build, tests, security, approval, health) and produce an ordered deployment plan with a rollback strategy per deploy strategy (rolling, blue-green, canary, recreate).

Request body

servicestringService name.required
environmentstringTarget environment, e.g. prod.required
versionstringVersion to release.required
strategystringrolling | blue-green | canary | recreate.
artifactsobjectGate statuses, e.g. {"build":"pass","tests":"pass"}.

Example request

curl -X POST https://api.patchr.co/v1/cicd/plan \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":"web","environment":"prod","version":"v2.0.0","strategy":"rolling","artifacts":{"build":"pass","tests":"pass"}}'

Response shape

{ "ok": true, "verdict": "ready|needsApproval|blocked", "gates": [...], "steps": [...], "rollback": {...} }
POST/v1/kubernetes/repairBearer token

Triage & repair Kubernetes

Triage a kubectl snapshot (pods + events) for CrashLoopBackOff, OOMKilled, ImagePullBackOff, and scheduling failures, and propose approval-gated remediations. Never mutates a live cluster.

Request body

podsarraykubectl get pods -o json items.required
eventsarraykubectl get events -o json items.

Example request

curl -X POST https://api.patchr.co/v1/kubernetes/repair \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pods":[...],"events":[...]}'

Response shape

{ "ok": true, "verdict": "...", "findings": [...], "remediations": [...], "approvals": [...] }
POST/v1/incident/respondBearer token

Incident triage

Correlate active alerts (and optional signals such as recent deploys) into a triaged incident with a probable cause and safe next actions. Mutating responses are approval-gated.

Request body

alertsarrayActive alert objects.required
signalsobjectCorrelation context, e.g. recentDeploys.

Example request

curl -X POST https://api.patchr.co/v1/incident/respond \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alerts":[{"name":"HighErrorRate","severity":"critical","service":"web"}],"signals":{"recentDeploys":[{"service":"web","version":"v2.0.0"}]}}'

Response shape

{ "ok": true, "incident": {...}, "actions": [...], "approvals": [...], "timeline": [...] }
POST/v1/database/migration/validateBearer token

Validate DB migration

Classify migration operations, check ordering, assess lock/downtime risk and reversibility, gate on backup readiness, and return post-migration checks. Validates and gates — it does not run migrations.

Request body

migrationsarrayMigration objects: {id, sql}.required
backupobjectBackup readiness context.
dialectstringpostgres (default), mysql, ...

Example request

curl -X POST https://api.patchr.co/v1/database/migration/validate \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"migrations":[{"id":"0002_drop_legacy","sql":"DROP TABLE legacy_orders;"}],"backup":{"recentBackup":false}}'

Response shape

{ "ok": true, "verdict": "...", "migrations": [...], "orderingIssues": [...], "postChecks": [...] }
POST/v1/security/validateBearer token

Security validation

Scan provided file contents for exposed secrets, insecure configuration, and risky permissions. Findings carry severity and redacted evidence, plus a release-gate verdict. Deterministic and offline.

Request body

filesobjectMap of {path: contents} to scan.required

Example request

curl -X POST https://api.patchr.co/v1/security/validate \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"files":{"config.js":"const key = \"AKIAIOSFODNN7EXAMPLE\";"}}'

Response shape

{ "ok": false, "verdict": "block", "findings": [...] }
POST/v1/delivery/runBearer token

Run delivery pipeline

Chain configure → validate → deploy → monitor → repair. Staging delivers end-to-end; production pauses at the deploy gate (status awaitingApproval) until resumed. Live deploys dispatch through a configured CI connector with idempotency.

Request body

servicestringService name.required
environmentstringstaging | prod.required
versionstringVersion to deploy.required
strategystringrolling | blue-green | canary | recreate.
artifactsobjectGate statuses.
filesobjectRepository files for the configure/validate stages.

Example request

curl -X POST https://api.patchr.co/v1/delivery/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":"web","environment":"prod","version":"v2.0.0","strategy":"rolling","artifacts":{"build":"pass","tests":"pass"},"files":{...}}'

Response shape

{ "runId": "run_...", "status": "delivered|awaitingApproval|blocked", "stages": [...], "handoff": {...} }
POST/v1/delivery/runs/{runId}/resumeBearer token

Resume delivery run

Resume a paused delivery run with a human approval decision. Approve to continue into deploy/repair; reject to block.

Path / query parameters

runIdstringThe runId from the paused run.required

Request body

approvedbooleantrue to approve, false to reject.required

Example request

curl -X POST https://api.patchr.co/v1/delivery/runs/run_abc123/resume \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved":true}'

Response shape

{ "runId": "run_abc123", "status": "delivered", "stages": [...] }
POST/v1/orchestrator/autonomousBearer token

Run autonomously (mandate)

Run a developer flow (delivery or environment) without a human, under an explicit autonomy mandate. Auto-approves the gates the mandate grants within an action budget and runs allow-listed setup commands through a guarded executor. Off unless autonomy.enabled is true (and the PICUX_AUTONOMY_ENABLED kill switch is not disabled); ungranted gates or an exhausted budget leave the run awaitingApproval (fail-closed).

Request body

modestringdelivery | environment (inferred from the payload when omitted).
autonomyobjectThe grant: {enabled, allowedActions, allowCommands, maxActions, dryRun, workdir, requireApproval}.required
…objectPlus the delivery/environment fields for the chosen mode (service, version, artifacts, files, ...).

Example request

curl -X POST https://api.patchr.co/v1/orchestrator/autonomous \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode":"delivery","service":"web","environment":"prod","version":"v2.0.0",
    "strategy":"rolling","artifacts":{"build":"pass","tests":"pass"},"files":{...},
    "autonomy":{"enabled":true,"allowedActions":["delivery.deploy","delivery.rollback"],"maxActions":6}
  }'

Response shape

{ "ok": true, "status": "delivered",
  "autonomy": { "autonomousToCompletion": true, "budgetUsed": 1,
    "actions": [{"action":"delivery.deploy","decision":"autoApproved","status":"delivered"}] },
  "result": {...} }
Back to top

Workflow Templates

Pre-packaged domain sequences for common work execution 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. "vendorDueDiligence" | "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/vendorDueDiligence/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendorName":"Acme Supply Co.","documents":["att_price_list","att_compliance_cert"],"policyRules":["priceVarianceUnder5pct","certificationCurrent"]}'
Back to top

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"
  }
}
GET/v1/audit/proofPacks/{packId}Bearer token

Fetch proof pack

Retrieve a saved proof pack by ID. Proof packs contain source snapshots, evidence hashes, contradiction records, decision logs, and receipts.

Path / query parameters

packIdstringProof pack identifier.required

Example request

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

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}'
Back to top

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 connector

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": [] }
Back to top

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"
Back to top

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 } }
Back to top

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"
Back to top

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"
Back to top

Schemas & Protocol

Machine-readable contract surfaces for validation, discovery, and integration-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

Integration-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"}'
Back to top

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"}'
Back to top

SDK Scenarios

Captured request and response JSON

These scenarios were run through the Patchr SDK against the public orchestrator contract. Use them as copy-ready starting points for shopping, claims, service calls, support disputes, and property lead discovery.

Shopping

NEEDS_INPUT

Route: hunt

Request JSON

{
  "clientId": "storefront_demo",
  "channel": "sdk",
  "conversationId": "conv_sdk_shopping",
  "request": "Buy used iPhone 12 in Sweden under 350 dollar",
  "country": "SE",
  "urls": ["https://marketplace.example.test/iphone-12"]
}

Response JSON

{
  "status": "NEEDS_INPUT",
  "route": ["hunt"],
  "results": {
    "hunt": {
      "inputKind": "choice",
      "choices": [{ "title": "Blocket iPhone 12 listing", "price": 320.0, "currency": "USD" }]
    }
  }
}

Damage Claim

ready

Route: resolve -> bridge

Request JSON

{
  "clientId": "claims_demo",
  "channel": "sdk",
  "conversationId": "conv_sdk_damage_claim",
  "request": "My newly purchased TV got damaged in transit from Example Electronics and support has not followed up.",
  "attachments": [{ "name": "damaged-tv-photo.jpg", "mime": "image/jpeg" }]
}

Response JSON

{
  "status": "ready",
  "route": ["resolve", "bridge"],
  "results": {
    "resolve": { "triage": { "risk": { "label": "damagedGoodsClaim", "severity": "medium" } } },
    "bridge": { "connectorCount": 9 }
  }
}

Lekki Mechanic Call

awaitingProxy

Route: hunt -> bridge -> proxy

Request JSON

{
  "clientId": "field_service_demo",
  "channel": "sdk",
  "conversationId": "conv_sdk_lekki_mechanic",
  "action": "contact",
  "itemId": "place_b0f2f11efc4bffe9a67db991",
  "consentToCall": true
}

Response JSON

{
  "status": "awaitingProxy",
  "route": ["hunt", "bridge", "proxy"],
  "results": {
    "bridge": { "status": "proxyHandoffReady", "mode": "proxyContact" },
    "proxy": { "mission": { "voiceCall": { "status": "readyToCall", "connectorId": "clientTwilioVoice" } } }
  }
}

Ticket Dispute

ready

Route: resolve -> bridge

Request JSON

{
  "clientId": "support_ops_demo",
  "channel": "sdk",
  "conversationId": "conv_sdk_ticket_dispute",
  "request": "Dispute support ticket ZD-44291: airline charged me twice after cancellation."
}

Response JSON

{
  "status": "ready",
  "route": ["resolve", "bridge"],
  "results": {
    "resolve": { "claimDraft": { "target": { "name": "bank", "type": "bank" } } },
    "bridge": { "contactPlan": { "primary": { "type": "secureMessage" } } }
  }
}

Property Lead

NEEDS_INPUT

Route: hunt

Request JSON

{
  "clientId": "property_demo",
  "channel": "sdk",
  "conversationId": "conv_sdk_property_partille",
  "request": "Buy abandoned property in Partille Goteborg under 2000000 SEK",
  "marketplaces": ["hemnet"]
}

Response JSON

{
  "status": "NEEDS_INPUT",
  "route": ["hunt"],
  "results": {
    "hunt": {
      "inputKind": "choice",
      "choices": [{ "title": "Partille renovation property", "price": 206353.18, "currency": "USD" }]
    }
  }
}
Full SDK guide

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