Build

API reference

The OpsKeeper HTTP API is the canonical interface for the control plane. The MCP tools in opskeeper-teamharness map one-to-one onto the endpoints below.

Base URL and authentication

All endpoints live under /api/v1. Authentication is Authorization: Bearer <jwt>. The JWT is issued by POST /api/v1/auth/login and refreshed via POST /api/v1/auth/refresh.

Incidents

incidents

GET    /api/v1/incidents
GET    /api/v1/incidents/:id
GET    /api/v1/incidents/:id/timeline
GET    /api/v1/incidents/:id/evidence
GET    /api/v1/incidents/:id/proposals
GET    /api/v1/incidents/:id/audit

Proposals

proposals

POST   /api/v1/proposals
GET    /api/v1/proposals/:id
POST   /api/v1/proposals/:id/approve
POST   /api/v1/proposals/:id/reject
GET    /api/v1/proposals/pending

Approving a proposal binds the approval to the proposal's resource, command, and payload hash. The control plane will refuse to dispatch a recovery against a mutated proposal.

Skills

skills

GET    /api/v1/skills
GET    /api/v1/skills/:name
POST   /api/v1/skills/:name/deploy
DELETE /api/v1/skills/:name
POST   /api/v1/skills/:name/rotate-secret

Audit

audit

GET    /api/v1/audit?from=&to=&incident_id=&limit=
POST   /api/v1/audit/replay    # walks the HMAC chain end-to-end
GET    /api/v1/audit/events/:id

Plugins

plugins

GET    /v1/plugins
GET    /v1/plugins/:id
POST   /v1/plugins/:id/install
POST   /v1/plugins/:id/uninstall
POST   /v1/plugins/:id/enable
POST   /v1/plugins/:id/disable
POST   /v1/plugins/:id/sync
POST   /v1/plugins/:id/push

Webhooks

webhooks

POST   /api/v1/webhook/alerts   # HMAC-signed by the source
POST   /api/v1/webhook/git        # for change-event correlation

Errors

All errors return a JSON body with code, message, and optionally details:

error

{
  "code": "proposal_hash_mismatch",
  "message": "resource, command, or payload hash does not match the approved proposal",
  "details": {
    "proposal_id": "prop-...",
    "expected_payload_hash": "sha256:...",
    "actual_payload_hash": "sha256:..."
  }
}

Middleware

The middleware layer is documented at docs/api/middleware.md in the repo. It covers rate limiting, request signing, and the audit middleware that emits a ledger event on every state-changing call.