API Reference Overview

The ProvenanceOne HTTP API provides programmatic access to all platform resources: workflows, runs, agents, skills, connections, approvals, datastores, secrets, the message bus, and workspace settings. All endpoints use HTTPS. Most endpoints require a JWT Bearer token or workspace API key. Webhook and bus inbound endpoints use HMAC-SHA256 authentication instead of JWT.

---

When to use

Use the API when you need to:

• Trigger workflows from external systems or CI/CD pipelines
• Integrate ProvenanceOne into a dashboard or monitoring tool
• Automate workspace setup (create connections, configure agents)
• Build event-driven pipelines using the message bus
• Pull audit events into a SIEM or compliance tool

---

Base URL

https://api.provenanceone.ai

All requests must use HTTPS. HTTP requests are not accepted.

---

Authentication

Three authentication methods are supported depending on the endpoint:

JWT Bearer token (the identity service)

Used for all standard authenticated endpoints when calling from a user session or server-side code that has completed the identity service auth flow.

Authorization: Bearer <jwt_token>

JWTs are issued by the platform identity service. They expire; your client must refresh them using the identity service token endpoint before expiry.

API key (x-api-key header)

Workspace API keys are created in Settings → API Keys and carry one or more of 16 named scopes. Pass the key in the x-api-key header.

x-api-key: <workspace_api_key>

API keys do not expire but can be revoked. Use API keys for server-to-server integrations where a user session is not available.

HMAC-SHA256 (webhooks and bus inbound)

Webhook endpoints (POST /webhooks/{workflowId}) and bus inbound endpoints (POST /bus/inbound/{subscriptionId}) do not accept JWT or API key auth. They validate an HMAC-SHA256 signature computed over the request body using a shared secret.

Include the signature in the request header:

X-ProvenanceOne-Signature: <hmac_sha256_hex>

Requests without a valid signature are rejected with 401.

---

Endpoint groups

Agents

GET/POST /agents, GET/PATCH/DELETE /agents/{id}, POST /agents/{id}/test-tool, GET/PUT/DELETE /agents/{id}/memory/{key}

Skills

GET/POST /skills, GET/PATCH/DELETE /skills/{id}, POST /skills/{id}/upload-url, POST /skills/{id}/run

Model integrations

GET/POST/PATCH/DELETE /settings/model-integrations, /settings/model-integrations/{id}

MCP Servers

GET/POST /mcp-servers, GET/PATCH/DELETE /mcp-servers/{id}, GET /mcp-servers/{id}/metrics, POST /mcp-servers/{id}/upload-url, POST /mcp-servers/{id}/connect, POST /mcp-servers/{id}/authorize, POST /mcp-servers/{id}/deploy, POST /mcp-servers/{id}/start, POST /mcp-servers/{id}/stop, GET /mcp-servers/{id}/logs

Connections

GET/POST /connections, GET/PATCH/DELETE /connections/{id}, POST /connections/{id}/authorize, POST /connections/{id}/test

Templates

GET /templates, GET /templates/{id} — read-only; returns available workflow templates

Workspace

GET/PUT /workspace, POST /workspace/switch, GET/PUT /workspace/environments, GET/PUT /workspace/notifications, GET/PUT /workspace/audit-digest, GET/POST /workspace/members, PUT/DELETE /workspace/members/{userId}, POST /workspace/members/{userId}/erase, GET/POST /workspace/api-keys, DELETE /workspace/api-keys/{keyId}

Workflows

GET/POST /workflows, GET/PUT/DELETE /workflows/{workflowId}, POST /workflows/{workflowId}/publish, GET /workflows/{workflowId}/versions, GET/PUT /workflows/{workflowId}/draft, POST /workflows/{workflowId}/trigger

Runs

GET/POST /runs, GET/DELETE /runs/{runId}, POST /runs/{runId}/cancel, POST /runs/{runId}/replay, GET /runs/{runId}/steps

Approvals

GET /approvals, GET/PATCH /approvals/{id}, POST /approvals/{id}/approve, POST /approvals/{id}/reject, POST /approvals/{id}/comments, GET/POST /delegated-grants/{grantId}/approve, GET/POST /delegated-grants/{grantId}/deny

Audit

GET /audit, GET /audit/{eventId}

Datastores

GET/POST /datastores, GET/PATCH/DELETE /datastores/{id}, GET /datastores/{id}/objects, POST /datastores/{id}/upload-url, GET/DELETE /datastores/{id}/objects/{key+}

Secrets

GET/POST /secrets, GET/PATCH/DELETE /secrets/{id}, POST /secrets/{id}/rotate, POST /secrets/{id}/reveal

MCP Gateway

GET/POST /gateway/policies, GET/PATCH/DELETE /gateway/policies/{id}, GET/PATCH /gateway/settings, POST /gateway/tokens/{id}/reveal

Bus

POST/GET /bus/messages, GET /bus/messages/{msgId}, POST/GET/PUT/DELETE /bus/subscriptions/{id}, GET/POST/DELETE /bus/api-keys, GET /bus/metrics, POST/GET/PATCH/DELETE /bus/schemas, POST /bus/inbound/{subscriptionId} (HMAC only, no JWT)

Webhooks

POST /webhooks/{workflowId} (HMAC only, no JWT)

Billing

GET /billing/summary, POST /billing/portal

WebSocket

Real-time updates via $connect, $disconnect, $default channels.

---

Example requests and responses

GET /workflows — list workflows

curl https://api.provenanceone.ai/workflows \
  -H "x-api-key: YOUR_KEY"

{
  "items": [
    {
      "workflowId": "wf_01HX...",
      "name": "Order Processing",
      "status": "deployed",
      "version": 3,
      "environment": "production",
      "updatedAt": "2026-04-28T14:22:00Z"
    }
  ],
  "nextCursor": "eyJ..."
}

POST /runs — trigger a workflow run

curl -X POST https://api.provenanceone.ai/runs \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf_01HX...",
    "input": {
      "orderId": "ORD-9921",
      "amount": 750.00
    }
  }'

{
  "runId": "run_01HY...",
  "workflowId": "wf_01HX...",
  "status": "running",
  "startedAt": "2026-05-01T09:00:00Z"
}

GET /runs/{runId} — get a run

curl https://api.provenanceone.ai/runs/run_01HY... \
  -H "x-api-key: YOUR_KEY"

{
  "runId": "run_01HY...",
  "workflowId": "wf_01HX...",
  "status": "completed",
  "startedAt": "2026-05-01T09:00:00Z",
  "completedAt": "2026-05-01T09:00:47Z",
  "durationMs": 47000,
  "input": { "orderId": "ORD-9921", "amount": 750.00 },
  "output": { "processed": true, "notificationSent": true }
}

POST /approvals/{id}/approve — approve an approval step

curl -X POST https://api.provenanceone.ai/approvals/appr_01HZ.../approve \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Reviewed and approved. Order is within policy limits."
  }'

{
  "approvalId": "appr_01HZ...",
  "status": "approved",
  "approvedBy": "user_01HA...",
  "approvedAt": "2026-05-01T09:05:00Z"
}

---

Pagination

List endpoints return a nextCursor field in the response when additional pages are available. Pass the cursor value as the cursor query parameter on the next request to retrieve the next page. An absent or null nextCursor indicates the last page.

curl "https://api.provenanceone.ai/audit?cursor=eyJ...&limit=100" \
  -H "x-api-key: YOUR_KEY"

---

WebSocket (real-time updates)

ProvenanceOne provides a WebSocket endpoint for real-time event streaming. Connect to $connect, send messages to $default, and disconnect via $disconnect. Use this to receive live run status updates, approval notifications, and bus delivery events without polling.

Authentication for the WebSocket connection uses the same JWT Bearer token as the REST API.

---

Webhook authentication (inbound)

External systems can trigger workflows by POSTing to POST /webhooks/{workflowId}. This endpoint does not accept JWT or API key auth. The request must include an HMAC-SHA256 signature computed over the raw request body using the shared secret configured for the webhook.

The platform validates the signature before the workflow is triggered. Invalid signatures return 401 and the workflow run is not started.

---

Error handling

The API uses standard HTTP status codes:

Code	Meaning
200	Success
201	Resource created
400	Bad request — check request body
401	Authentication failed — invalid or missing credentials
403	Authorisation failed — valid credentials but insufficient scope or role
404	Resource not found
409	Conflict — resource already exists or state conflict
429	Rate limited
500	Internal server error

---

Rate limits

Rate limits apply per API key and per JWT identity. If a request is rate limited, the response is 429 Too Many Requests. Check the Retry-After header for the number of seconds to wait before retrying.

---

Common mistakes

• Using a JWT where an API key is required. Some CI/CD or server-side contexts require API keys (JWTs expire and require a user session to refresh). Use API keys for long-running server integrations.
• Forgetting the Content-Type: application/json header on POST/PATCH requests. Requests without this header may be rejected or return unexpected behaviour.
• Using the webhook endpoint (/webhooks/{workflowId}) for internal workflow triggering. For internal triggers, use POST /workflows/{workflowId}/trigger or POST /runs with JWT or API key auth — these are more reliable and return a run ID directly.
• Not handling nextCursor in list responses. If you only read the first page of results, you may miss records. Always paginate until nextCursor is null.

---

Troubleshooting

401 on all requests — verify the JWT is not expired (the identity service tokens typically expire after 1 hour) or the API key is not revoked. Check you are using the correct header (Authorization: Bearer for JWT, x-api-key for API keys).

403 on a specific endpoint — the credentials are valid but the scope or role is insufficient. Check the required scope for that endpoint and update the API key's scope list in Settings, or use an account with the required role.

Webhook returns 401 — the HMAC signature is invalid. Verify the external system is signing the raw (not parsed) request body with the correct shared secret using HMAC-SHA256, and that the signature is in the correct header.

POST /runs returns 404 — confirm the workflowId is correct and the workflow is in deployed status. Draft workflows cannot be triggered.

---

Security and permissions

All API traffic uses TLS 1.2 or higher. API keys are workspace-scoped and carry explicit permission scopes. JWTs are issued by the identity service and carry workspace membership and role claims. Audit events are emitted for every significant API action.

See /docs/security for the full authentication and authorisation model.

---

Related pages

• Security Model
• Workflows
• Workflow Runs
• Audit Log
• Message Bus
• Settings

---

FAQ