API Reference

Base URL: https://api.sandbox.openprodkt.com

Interactive docs: Swagger UI and OpenAPI JSON

This reference is organized by module so customers can find the surface they need without needing to know the implementation details behind it.

Prefer a language client? See SDKs.

Conventions

List endpoints accept limit (1-100, default 25) and offset, and return total alongside the results. Most also accept search for case-insensitive partial matching.

GET /v1/assets?limit=25&offset=0&search=invoice

Write operations additionally require an appropriate role. See Auth and Access.

Public endpoints

Method	Path	Description
GET	/health	Health check
GET	/docs	Interactive API docs
GET	/swagger	Interactive API docs (legacy alias)
GET	/openapi.json	OpenAPI schema (JSON)
GET	/openapi.yaml	OpenAPI schema (YAML)

Authentication

OpenProdkt uses two credential types:

1. JWT for human Console sessions.
2. API keys for machine workloads.

Header format:

Authorization: Bearer <jwt-or-api-key>

Identity and workspace

This module covers organization setup, sign-in, profile access, settings, and member invites.

Method	Path	Purpose
POST	/auth/register	Create an organization and first owner
GET	/auth/onboarding-requests/{id}	Check onboarding request status
POST	/auth/request-code	Request one-time login code
POST	/auth/verify	Exchange code for JWT
POST	/auth/logout	Revoke the current session
GET	/me	Current user profile
GET	/settings	Workspace settings
GET	/members	List workspace members
POST	/members	Invite workspace member
POST	/members/{id}/activate	Reactivate a member
POST	/members/{id}/deactivate	Deactivate a member

Register example:

{
  "organizationName": "Acme Ltd",
  "email": "owner@acme.com"
}

Governance decisions

This module covers decision evaluation and the playground. Applications call /v1/evaluate through an SDK or framework adapter. The transparent proxy calls /v1/proxy/evaluate. Both use the same canonical request.

Method	Path	Caller	Purpose
POST	/v1/evaluate	SDKs and framework adapters	Authorize an operation
POST	/v1/proxy/evaluate	Transparent proxy (requires proxy.enabled)	Authorize a proxied request; never returns 202
POST	/v1/playground/decision	Console playground	Test a policy; not an application contract

Request example:

{
  "version": "v1",
  "asset": { "id": "ast_e8f1a2c3" },
  "operation_id": "pay-2026-001",
  "transport": { "kind": "http" },
  "metadata": {
    "operation": "payment.execute",
    "amount": 12000,
    "currency": "USD"
  }
}

operation_id is required and must identify one business operation. Put all context inside metadata. Top-level action, amount, and workflow fields are rejected with 400.

Typical pending response (/v1/evaluate, HTTP 202):

{
  "version": "v1",
  "operation_id": "pay-2026-001",
  "decision": "approval_required",
  "decisionId": "dec_9f2a1c4e",
  "approvalId": "apr_5c6d7e8f",
  "approvalStatus": "pending",
  "payload_hash": "sha256:<hash>",
  "approval_expires_at": "2026-09-13T11:15:00Z"
}

Status codes:

Status	Meaning
200	Allowed, including a validated redemption of an approved operation
202	Approval pending (/v1/evaluate only)
400	Invalid request
402	Decision, approval, or notification quota exhausted
403	Denied, or the approval is rejected, expired, revoked, or consumed. On /v1/proxy/evaluate, a pending approval also returns 403 with a challenge
404	Referenced approval does not exist
409	asset_identity_conflict, operation_id_conflict, approval_retry_mismatch, or operation_in_progress
503	Policy evaluation failed; the request fails closed

Inventory

This module covers the inventory concepts customers use to describe what they are governing.

Method	Path
GET, POST	/v1/assets
PATCH, DELETE	/v1/assets/{id}
GET, POST	/v1/groups
PATCH, DELETE	/v1/groups/{id}
GET	/v1/integration-presets

Asset discovery

Detection points report assets that are not yet registered. Requires the asset_discovery:write scope.

Method	Path	Purpose
POST	/v1/asset-discoveries	Submit an observation
GET	/v1/asset-discoveries	List pending observations
DELETE	/v1/asset-discoveries/{id}	Dismiss an observation

Discovery is observation only. It does not evaluate a policy, return an outcome, or create a decision. The discovery_id you supply is the idempotency key, so repeated sightings aggregate rather than duplicate.

{
  "discovery_id": "dsc_01J...",
  "asset": {
    "key": "billing.refund-api",
    "displayName": "Billing Refund API",
    "kind": "rest_api",
    "environment": "production"
  },
  "metadata": { "operation": "refund", "amount": 250 }
}

Asset example:

{
  "name": "invoice-agent",
  "environment": "sandbox",
  "group": "payments"
}

Group example:

{
  "name": "payments",
  "approvers": "finance-lead@acme.com,owner@acme.com"
}

Policies

This module covers policy creation and lifecycle.

Method	Path
GET, POST	/v1/policies
PATCH, DELETE	/v1/policies/{id}
POST	/v1/policies/{id}/clone
GET	/v1/policies/{id}/revisions
PATCH	/v1/policies/{id}/activation
POST	/v1/policies/{id}/rollback

Every change to a policy creates a revision. rollback restores an earlier revision and records the rollback as a new revision, so history is never discarded.

Policy condition example:

{
  "field": "amount",
  "operator": ">",
  "value": 5000
}

Approvals and history

This module covers the review queue and traceability surfaces. See Approvals & Webhooks for the full delivery model (webhook, app-managed retry, short wait, polling).

Method	Path	Purpose
GET	/v1/approvals	List pending/resolved approvals
GET	/v1/approvals/{id}	Get a single approval (polling/short-wait)
POST	/v1/approvals/{id}/approve	Approve decision
POST	/v1/approvals/{id}/reject	Reject decision
POST	/v1/approvals/{id}/revoke	Revoke a pending or approved approval
GET	/v1/decision-explorer	Decision history
GET	/v1/audit	Audit trail
GET	/v1/usage	Usage counters

Approval example:

{
  "id": "apr_5c6d7e8f",
  "decisionId": "dec_9f2a1c4e",
  "assetId": "invoice-agent",
  "policyId": "pol_8a1b2c3d",
  "requesterId": "key_4f5e6d7c",
  "status": "pending",
  "expiresAt": "2026-09-13T11:15:00Z"
}

Webhooks

Register an endpoint to receive signed, async approval lifecycle events — the recommended delivery model over polling. See Approvals & Delivery.

Method	Path	Purpose
GET, POST	/v1/webhooks	List / register a webhook endpoint
POST	/v1/webhooks/{id}/rotate	Rotate the signing secret
DELETE	/v1/webhooks/{id}	Remove a webhook endpoint

Event types: approval.pending, approval.approved, approval.rejected, approval.expired, and approval.revoked. Each delivery includes X-OpenProdkt-Event-Id and X-OpenProdkt-Timestamp headers. X-OpenProdkt-Signature uses the form v1=sha256=<hex> and contains an HMAC-SHA256 of the exact timestamp header, a period, and the raw request body, using the endpoint secret (shown once, at creation or rotation).

Access and permissions

This module covers API keys and machine permissions.

Method	Path
GET, POST	/v1/api-keys
POST	/v1/api-keys/{id}/rotate
POST	/v1/api-keys/{id}/revoke

Delivery and integrations

This module covers the public API and SDK contract.

Surface	Path
API docs	/swagger
OpenAPI schema	/openapi.json

Response expectations

1. Success responses return JSON.
2. Validation errors return 400.
3. Authentication failures return 401.
4. Permission failures return 403.
5. State conflicts return 409.
6. Rate or quota limits return 429.

Only 429 and 5xx responses are worth retrying. See the Developer Guide for retry and pagination guidance.

Source of truth

Use /openapi.json for exact request and response schemas.