Skip to main content

docs/api.md

Imported Content​

API Surface

Base path​

  • /api/v1

Required headers​

  • x-workspace-id: required on tenant-scoped routes.
  • Idempotency-Key: required on all mutating routes.
  • x-correlation-id: optional; generated if absent.
  • Authorization: Bearer <jwt>: required unless AUTH_MODE=disabled.
  • x-agentfield-signature: required on workflow callback when webhook secret is configured.
  • x-agentfield-delivery: required on workflow callback when signatures are enforced.
  • x-hub-signature-256: required on GitHub webhook when enabled.
  • x-github-delivery: required on GitHub webhook when enabled.

Role model (JWT roles claim)​

  • msp_admin: full platform access
  • ops_engineer: operations + telemetry + execution access
  • automation_operator: allowed to execute agents
  • integration_admin: accounting/notification adapter operations
  • billing: financial resource access
  • data_admin: import/export and broad write capabilities
  • viewer: read-only operational visibility
  • platform_admin: non-tenant platform configuration and secret management
  • endpoint_agent: telemetry ingest + edge policy access
  • client_portal: scoped client-facing read access

Aggregation endpoints​

  • GET /api/v1/dashboard/summary: server-side KPI/event/execution aggregation for operator console.
  • GET /api/v1/portal/summary: portal counters, approvals queue, ticket and invoice summary.
  • GET /api/v1/ops/summary: incident/change/billing lane summaries for ops workbench.

Portal action interfaces​

  • POST /api/v1/portal/session/exchange
  • POST /api/v1/portal/session/terminate
  • GET /api/v1/portal/invites
  • POST /api/v1/portal/invites
  • POST /api/v1/portal/invites/{id}/revoke
  • GET /api/v1/portal/knowledge-base
  • GET /api/v1/portal/clients
  • GET /api/v1/portal/tickets
  • GET /api/v1/portal/quotes
  • GET /api/v1/portal/invoices
  • GET /api/v1/portal/payments
  • POST /api/v1/portal/tickets
  • POST /api/v1/portal/tickets/{id}/update
  • POST /api/v1/portal/quotes/{id}/decision
  • POST /api/v1/portal/invoices/{id}/acknowledge
  • POST /api/v1/portal/invoices/{id}/payment-intent

Operations action interfaces​

  • POST /api/v1/ops/alerts/{id}/link-ticket
  • POST /api/v1/ops/tickets/{id}/link-asset
  • POST /api/v1/ops/tickets/{id}/link-runbook
  • POST /api/v1/ops/tickets/{id}/escalate
  • POST /api/v1/ops/tickets/{id}/resolve

Workflow control interfaces​

  • GET /api/v1/workflow-executions/{id}
  • POST /api/v1/workflow-executions/{id}/retry
  • POST /api/v1/workflow-executions/{id}/cancel

WorkflowExecution includes:

  • inputRef, outputRef, evidenceRef
  • durationMs, retryCount, failureCode

Agent runtime visibility interfaces​

  • GET /api/v1/agent-runtime/health
  • GET /api/v1/agent-runtime/queues
  • GET /api/v1/agent-runtime/failures
  • GET /api/v1/agent-runtime/agents
  • POST /api/v1/agent-runtime/outbox-failures/{id}/retry
  • POST /api/v1/agent-runtime/job-failures/{id}/retry
  • POST /api/v1/agent-runtime/smoke

Telemetry enrollment interfaces​

  • GET /api/v1/edge-agent/enrollment
  • POST /api/v1/edge-agent/enrollment/rotate
  • GET /api/v1/edge-agent/ingest-status

Primary endpoints​

  • GET /health
  • GET /api/v1/health
  • GET /.well-known/engine-status
  • GET /api/v1/openapi
  • GET /api/v1/events/outbox
  • GET /api/v1/events/ingest-batches
  • POST /api/v1/events/ingest
  • GET /api/v1/edge-agent/policy
  • GET /api/v1/edge-agent/enrollment
  • POST /api/v1/edge-agent/enrollment/rotate
  • GET /api/v1/edge-agent/ingest-status
  • POST /api/v1/execute/{agent}.{reasoner}
  • GET /api/v1/workflow-executions
  • GET /api/v1/workflow-executions/{id}
  • POST /api/v1/workflow-executions/{id}/retry
  • POST /api/v1/workflow-executions/{id}/cancel
  • GET /api/v1/audit-credentials
  • GET /api/v1/portal/knowledge-base
  • GET /api/v1/portal/clients
  • GET /api/v1/portal/tickets
  • GET /api/v1/portal/quotes
  • GET /api/v1/portal/invoices
  • GET /api/v1/portal/payments
  • POST /api/v1/portal/session/exchange
  • POST /api/v1/portal/session/terminate
  • GET /api/v1/portal/invites
  • POST /api/v1/portal/invites
  • POST /api/v1/portal/invites/{id}/revoke
  • POST /api/v1/portal/tickets
  • POST /api/v1/portal/tickets/{id}/update
  • POST /api/v1/portal/quotes/{id}/decision
  • POST /api/v1/portal/invoices/{id}/acknowledge
  • POST /api/v1/portal/invoices/{id}/payment-intent
  • POST /api/v1/ops/alerts/{id}/link-ticket
  • POST /api/v1/ops/tickets/{id}/link-asset
  • POST /api/v1/ops/tickets/{id}/link-runbook
  • POST /api/v1/ops/tickets/{id}/escalate
  • POST /api/v1/ops/tickets/{id}/resolve
  • GET /api/v1/agent-runtime/health
  • GET /api/v1/agent-runtime/queues
  • GET /api/v1/agent-runtime/failures
  • GET /api/v1/agent-runtime/agents
  • POST /api/v1/agent-runtime/outbox-failures/{id}/retry
  • POST /api/v1/agent-runtime/job-failures/{id}/retry
  • POST /api/v1/agent-runtime/smoke
  • POST /api/v1/webhooks/workflow-completed
  • POST /api/v1/integrations/github/webhook
  • POST /api/v1/integrations/accounting/sync
  • POST /api/v1/integrations/notifications/test
  • POST /api/v1/imports
  • POST /api/v1/exports
  • GET /api/v1/jobs
  • GET /api/v1/platform/settings
  • PUT /api/v1/platform/settings
  • GET /api/v1/platform/secrets
  • POST /api/v1/platform/secrets/{key}
  • GET /api/v1/workspace/settings
  • PUT /api/v1/workspace/settings
  • GET /api/v1/workspace/secrets
  • POST /api/v1/workspace/secrets/{key}

Resource endpoint pattern​

For each resource (clients, tickets, invoices, etc.):

  • GET /api/v1/{resource}
  • GET /api/v1/{resource}/{id}
  • POST /api/v1/{resource}
  • PUT /api/v1/{resource}/{id}
  • PATCH /api/v1/{resource}/{id}
  • DELETE /api/v1/{resource}/{id}

List routes support shared query conventions:

  • limit: page size
  • offset: page offset
  • sortBy: whitelisted sort field
  • sortOrder: asc or desc
  • q: free-text filter across serialized payload

List responses return envelope metadata:

  • data: list payload
  • page: { limit, offset, returned, total }
  • sort: { by, order }
  • filters: current filter state

Job contract fields​

GET /api/v1/jobs returns expanded lifecycle metadata:

  • queuedAt, startedAt, completedAt
  • retryCount
  • errorCode, errorMessage
  • artifactUrl

Event topics​

  • ticket.created
  • ticket.sla_breached
  • asset.state_changed
  • alert.triggered
  • invoice.overdue
  • pipeline.failed
  • workflow.completed

Integration notes​

  • GitHub webhook route returns 404 when GITHUB_WEBHOOK_ENABLED=false.
  • Telemetry ingest enforces Idempotency-Key for replay-safe ingestion.