API

Base path /api/v1; the OpenAPI document is served at /api/v1/openapi.json and the interactive browser at /api/v1/docs. Program routes live under /programs/{program_id}/... (constant PROGRAM_PREFIX in app/routers/_scope.py), organisation routes under /orgs/current/.... The API is designed: 117 routes are mounted and answer with the contract’s DTOs, connection providers and tools are stubs, and the agent runtime is a fake unless AGENT_RUNTIME_URL is set. Design target host api.trovensa.com; local http://localhost:8100.

Conventions

• Every list route returns Page[T] (items[], total, limit, offset) with limit 1 to 200 (default 50) and offset from 0.
• Every *Out carries id, created_at, updated_at; scoped rows carry organization_id, program_id, stage_id; agent-capable rows carry origin, agent_run_id, illustrative.
• Exactly one require_permission(...) per route (the RBAC matrix test fails on any unlisted mounted route). Health routes are public; /me, /permissions, /personas and /providers need only a valid token.
• Every mutation writes an audit row <target>.<verb> in the same transaction (app/services/audit.py::write_audit); the worker writes no audit rows.
• Request bodies are capped by BodySizeLimitMiddleware; protocols, reports and SOPs get the larger document limit.
• Success codes: 201 on create, 202 when a run is queued (sync, agent-runs, checks, invocations), 204 on delete, otherwise 200.

Errors: problem+json

Errors are RFC 7807 documents with media type application/problem+json. type is https://console.trovensa.com/errors/<slug> (for example .../forbidden), and every document carries the request_id that the X-Request-ID response header also exposes. A 403 adds permission; a 422 adds errors[] with loc, msg, type.

{
  "type": "https://console.trovensa.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "this action requires permission evidence.hypotheses.approve",
  "request_id": "6f1c0d0e-illustrative",
  "permission": "evidence.hypotheses.approve"
}

Without a token every non-health route answers 401 with a WWW-Authenticate: Bearer challenge.

Identity and the development mode

Production tokens are RS256 from the identity provider with issuer and audience pinned by AUTH_ISSUER, AUTH_AUDIENCE and AUTH_JWKS_URL. Development and tests use HS256 tokens with header kid: dev signed with DEV_TOKEN_SECRET; they are accepted only when APP_ENV is dev or test, and validate_deployed_secrets() refuses to start a deployed environment that still carries the placeholder secret. Mint one with:

uv run python scripts/dev_token.py --user owner@example.com --org trovensa-demo --roles org_owner,program_owner

Routes

117 designed routes, grouped by router in mount order (ROUTERS in app/main.py). The legacy router (410 responses for retired paths) is mounted last and is empty.

Router health (2)

Router me (1)

Router permissions (1)

Router personas (1)

Router providers (1)

Router orgs (14)

Router programs (7)

Router connections (6)

Router agent_runs (4)

Router evidence (22)

Router plans (26)

Router review (16)

Router progress (16)

Providers

GET /providers returns the four connection providers of app/integrations/registry.py, every one designed:

Agent runs

POST .../evidence/agent-runs (kind in evidence_compare, evidence_gaps, evidence_hypotheses with a question_id), POST .../plans/agent-runs (plans_draft_protocol, plans_draft_report with a plan_id) and POST .../review/checks (review_check) create an AgentRunOut in status queued. The worker claims it, drives the runtime through bootstrap, start, status, submit, and writes the result as new records with origin = agent: findings and hypotheses with an assertion_kind, drafts in status draft, review findings with decision open. Public error codes on failure: runtime_unavailable, session_lost, budget_exhausted, timed_out, cancelled_by_user, attribution_leak, internal_error.

Source: api/app/main.py, api/app/routers/_scope.py, api/app/routers/health.py, api/app/routers/me.py, api/app/routers/permissions.py, api/app/routers/personas.py, api/app/routers/providers.py, api/app/routers/orgs.py, api/app/routers/programs.py, api/app/routers/connections.py, api/app/routers/agent_runs.py, api/app/routers/evidence.py, api/app/routers/plans.py, api/app/routers/review.py, api/app/routers/progress.py, api/app/errors.py, api/app/config.py, api/app/integrations/registry.py, api/app/services/agent_runtime.py, api/scripts/designed-routes.json, api/README.md