Skip to main content

docs/api.md

Metadata​

  • Purpose: Project documentation source file.
  • Domain: documentation
  • Language: md
  • Bytes: 6664
  • Lines: 203
  • Content hash (short): bd28bf28
  • Source (start): docs/api.md:1
  • Source (end): docs/api.md:203

Indexed Symbols​

No indexed functions/methods detected in this file.

Markdown Headings (if applicable)​

  • H1: API Surface (line 1)
  • H2: Base path (line 3)
  • H2: Required headers (line 7)
  • H2: Role model (JWT `roles` claim) (line 18)
  • H2: Aggregation endpoints (line 31)
  • H2: Portal action interfaces (line 37)
  • H2: Operations action interfaces (line 56)
  • H2: Workflow control interfaces (line 64)
  • H2: Agent runtime visibility interfaces (line 75)
  • H2: Telemetry enrollment interfaces (line 85)
  • H2: Primary endpoints (line 91)
  • H2: Resource endpoint pattern (line 154)
  • H2: Job contract fields (line 180)
  • H2: Event topics (line 189)
  • H2: Integration notes (line 199)

Source Preview​

# 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