API Reference

Complete reference for the Tempered REST API. All endpoints are under /api/v1/.

Authentication

All API requests require a Bearer token:

Authorization: Bearer prx_your_api_key_here

See Authentication for details on creating and managing API keys.

Base URL

https://your-tempered-instance/api/v1/

Response Format

All responses use JSON. Successful responses return 2xx status codes. Errors return structured JSON:

{
  "detail": "Error description"
}

Validation errors return field-level details:

{
  "description": ["This field is required."],
  "profile": ["Profile 'invalid' not found."]
}

Evaluations

Submit an Evaluation

POST /api/v1/evaluations/

Creates a new evaluation and queues it for processing.

Request Body:

Field	Type	Required	Description
`description`	string	Yes	What you're planning to do. Be specific — include what, why, and what's affected.
`profile`	string	No	Profile slug (default: `standard`). Options: `standard`, `dual-vendor`, `quorum-small`, `quorum-large`, `critical`, `debate`
`context`	object	No	Structured metadata (environment, services affected, rollback plan, etc.)
`change_request_id`	string	No	External change management reference (e.g., `CHG-2024-0456`)
`plan_id`	string	No	External plan reference
`idempotency_key`	string	No	Prevents duplicate evaluations on retry
`knowledge_document_ids`	array	No	UUIDs of knowledge documents to include in the analysis

Example:

{
  "description": "Upgrade PostgreSQL from 15 to 16 on the production cluster. Motivation: improved query planner for join-heavy workloads on the orders table. Affects: order-service, reporting-dashboard, nightly batch jobs. 5,000 active customers during maintenance window.",
  "profile": "dual-vendor",
  "context": {
    "environment": "production",
    "services_affected": ["order-service", "reporting-dashboard"],
    "rollback_plan": "Blue-green switchback, tested in staging",
    "maintenance_window": "Sunday 02:00-06:00 UTC"
  },
  "idempotency_key": "pg-upgrade-2026-03-09"
}

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "description": "Upgrade PostgreSQL from 15 to 16...",
  "profile": "dual-vendor",
  "submitted_at": "2026-03-09T10:30:00Z"
}

Get Evaluation Result

GET /api/v1/evaluations/{id}/

Returns the full evaluation result. Poll this endpoint until status is completed or failed.

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "description": "Upgrade PostgreSQL from 15 to 16...",
  "recommendation": "PROCEED_WITH_MITIGATIONS",
  "approved": true,
  "opinions": [
    {
      "vendor_name": "anthropic",
      "model_id": "claude-sonnet-4-6",
      "recommendation": "PROCEED_WITH_MITIGATIONS",
      "confidence": 0.85,
      "dimensions": {
        "security": {"level": "low", "rationale": "Standard upgrade path, no new attack surface"},
        "reliability": {"level": "medium", "rationale": "Brief downtime during switchover"},
        "compliance": {"level": "low", "rationale": "No data handling changes"},
        "operational": {"level": "medium", "rationale": "Requires DBA verification of query plans"},
        "business": {"level": "low", "rationale": "Maintenance window minimises impact"}
      },
      "conditions": ["Verify query execution plans in staging match production patterns"],
      "reasoning": "PostgreSQL major version upgrades are well-tested..."
    }
  ],
  "conditions": ["Verify query execution plans in staging match production patterns"],
  "quality_score": 0.87,
  "change_request_id": null,
  "plan_id": null,
  "submitted_at": "2026-03-09T10:30:00Z",
  "completed_at": "2026-03-09T10:30:12Z"
}

List Evaluations

GET /api/v1/evaluations/

Returns a paginated list of evaluations for your organisation.

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `processing`, `completed`, `failed`
`page`	integer	Page number (default: 1)
`page_size`	integer	Results per page (default: 20, max: 100)

Profiles

List Profiles

GET /api/v1/profiles/

Returns available evaluation profiles for your organisation.

Get Profile Detail

GET /api/v1/profiles/{id}/

Returns full configuration for a profile, including vendor settings, strategy, and consensus method.

Knowledge Documents

Upload documents that provide standing context for evaluations (security policies, architecture diagrams, compliance requirements).

List Documents

GET /api/v1/knowledge/

Upload Document

POST /api/v1/knowledge/

Request Body (multipart/form-data):

Field	Type	Required	Description
`title`	string	Yes	Document title
`content`	file	Yes	Document file (markdown, text, or PDF)

Get Document

GET /api/v1/knowledge/{id}/

Delete Document

DELETE /api/v1/knowledge/{id}/

Organisation

Get Organisation

GET /api/v1/org/

Returns organisation details including the embedded profile (sector, compliance frameworks, risk appetite).

Update Organisation Profile

PATCH /api/v1/org/profile/

Updates the organisation's extended profile. Requires admin scope.

Request Body (all fields optional):

{
  "sector": "financial_services",
  "organisation_size": "medium",
  "compliance_frameworks": ["uk_gdpr", "fca_handbook", "iso_27001"],
  "risk_appetite": "conservative",
  "data_classification_level": "confidential",
  "processes_personal_data": true,
  "regulated_industry": true,
  "regulator_names": ["FCA", "ICO"]
}

The profile data is automatically injected into Tempered evaluation prompts, enriching the analysis with your organisation's specific context.

API Keys

GET    /api/v1/org/api-keys/          # List keys
POST   /api/v1/org/api-keys/          # Create key
DELETE /api/v1/org/api-keys/{id}/      # Delete key
POST   /api/v1/org/api-keys/{id}/revoke/  # Revoke key

Members

GET    /api/v1/org/members/           # List members
POST   /api/v1/org/members/           # Invite member
DELETE /api/v1/org/members/{id}/      # Remove member

Webhooks

List Webhooks

GET /api/v1/webhooks/

Create Webhook

POST /api/v1/webhooks/

Request Body:

{
  "url": "https://your-app.example.com/webhooks/praxis",
  "events": ["evaluation.completed", "evaluation.failed"]
}

Response:

{
  "id": "wh-uuid-here",
  "url": "https://your-app.example.com/webhooks/praxis",
  "secret": "whsec_your_signing_secret",
  "events": ["evaluation.completed", "evaluation.failed"],
  "is_active": true
}

Update Webhook

PATCH /api/v1/webhooks/{id}/

Delete Webhook

DELETE /api/v1/webhooks/{id}/

See Webhook Integration for signature verification and retry policy details.

Billing

Check Usage

GET /api/v1/billing/subscription/usage/

Returns current billing period usage against your tier limits.

Pagination

List endpoints return paginated results:

{
  "count": 42,
  "next": "https://your-instance/api/v1/evaluations/?page=2",
  "previous": null,
  "results": [...]
}

Rate Limits

Default: 100 evaluations per hour
Enterprise: Configurable

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

Idempotency

Include an idempotency_key with evaluation submissions to prevent duplicates on retry. If the same key is submitted twice, Tempered returns the existing evaluation instead of creating a new one.

Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request — check the error details
`401`	Unauthorised — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not found
`429`	Rate limited — retry after the `Retry-After` header
`500`	Server error — retry with exponential backoff