API Reference

Aira's backend exposes a REST API under /api/v1 with 56 route modules and 200+ endpoints. This document covers authentication, the main endpoint groups, and the SSE streaming pattern.

Authentication

Five authentication methods:

JWT Bearer tokens

Obtain tokens via /api/v1/auth/login. Include the access token in requests:

Authorization: Bearer <access_token>

• Access tokens expire in 30 minutes
• Refresh tokens expire in 7 days
• Refresh via POST /api/v1/auth/refresh

API keys

Create API keys via POST /api/v1/auth/api-keys. Include in requests:

X-API-Key: <api_key>

API keys are scoped to a specific project and have configurable permissions and expiry.

Passkeys (WebAuthn/FIDO2)

For browser-based passwordless authentication. Register passkeys, then authenticate with biometrics or hardware keys.

SSO / OIDC

Enterprise single sign-on via OpenID Connect. Aira discovers the IdP configuration from the user's email domain.

Magic links

Passwordless email-based login. A one-time link is sent to the user's email with an optional next_path redirect.

Project scoping

All project-scoped endpoints require the project ID header:

X-Project-Id: <project_uuid>

The server validates that the authenticated user is a member of the specified project. Missing header returns 400, non-member returns 403.

Endpoint groups

Auth (/auth)

Registration, login, token refresh, logout, password reset (OTP-based), email verification, magic links, Google OAuth, SSO/OIDC exchange, API key management, passkey registration/authentication, security activity log.

Projects (/projects)

CRUD for projects. Create, list, get, update, delete. Project membership management. Project brief submission. Project settings.

Sources (/sources)

Add and manage source documents. Upload files, paste text, connect repositories.

Key endpoints:

• POST /sources/upload — File upload with content type detection
• POST /sources/{id}/analyze — Trigger knowledge ledger ingestion. Returns a run ID for SSE streaming.
• GET /sources/{id}/analysis — Stream analysis results via SSE

Knowledge (/knowledge)

Direct access to the knowledge ledger:

• GET /knowledge/summary — Working summary of project knowledge
• GET /knowledge/atoms — List/filter atoms (by kind, domain, tags, entity)
• GET /knowledge/contradictions — Open contradictions
• POST /knowledge/retrieve — Ranked retrieval (entity-linked -> metadata-filtered -> FTS fallback)
• GET /knowledge/runs/{run_id}/stream — SSE stream for ingestion run events
• POST /knowledge/atoms/{id}/verify — Human verification of an atom (HITL)
• POST /knowledge/contradictions/{id}/resolve — Resolve a contradiction with rationale
• POST /knowledge/merges/{id}/approve — Approve/reject a merge operation
• POST /knowledge/contradictions/rebuild — Rebuild contradiction detection

Insights (/insights)

User-facing projection of knowledge atoms. List, filter, create, update, delete.

Key endpoints:

• POST /insights/synthesize — Synthesize insights into a narrative
• POST /insights/{id}/verify — Verify insight with web corroboration
• POST /insights/merge — Merge duplicate insights
• GET /insights/{id}/citations — Get citation references for an insight

Features (/features)

Feature CRUD plus AI generation:

• POST /features/generate — Iterative feature generation with SSE streaming
• POST /features/{id}/breakdown — Break down a feature into tasks
• POST /features/{id}/quality — Quality assessment with SSE streaming

Tasks (/tasks)

Task CRUD, search, status updates, sprint assignment.

Key endpoints:

• POST /tasks/{id}/assign — Assign a task to a team member
• POST /tasks/rebalance — Get workload rebalance recommendations
• POST /tasks/rebalance/approve — Approve a rebalance proposal
• POST /tasks/rebalance/apply — Apply rebalance actions

Sprints (/sprints)

Sprint lifecycle: create, plan, commit scope, start, complete.

• POST /sprints/{id}/plan — Auto-plan sprint with SSE streaming
• POST /sprints/{id}/commit — Commit sprint scope and activate
• GET /sprints/current — Get the active sprint

Team (/team)

Team member management. Add, update, remove members. Skills, capacity, workload queries.

Team Ledger (/team-ledger)

Internal team intelligence:

• POST /team-ledger/objectives/ingest — Ingest team objectives from operational signals
• GET /team-ledger/metrics — Team member performance metrics
• POST /team-ledger/testimony/ingest — Ingest chat testimony
• GET /team-ledger/testimony/themes — Extracted testimony themes
• GET /team-ledger/testimony/contradictions — Team dynamics contradictions
• POST /team-ledger/testimony/escalations — List escalation cases
• GET /team-ledger/fairness/policy — Active fairness policy
• POST /team-ledger/fairness/policy/review — Review/update fairness policy
• GET /team-ledger/rebalance/decision — Get rebalance decision details
• GET /team-ledger/rebalance/candidates — Get candidate plans

Agents (/agents)

AI agent provisioning, management, and monitoring:

• POST /agents — Provision a new AI agent
• PATCH /agents/{id} — Update agent configuration
• POST /agents/{id}/pause, /resume, /terminate — Lifecycle control
• POST /agents/{id}/vm/spawn, /start, /stop, /restart — VM management
• DELETE /agents/{id}/vm — Delete agent VM
• GET /agents/{id}/vm/status — VM status
• GET /agents/{id}/status — Live agent status
• GET /agents/{id}/stats — Agent statistics
• GET /agents/{id}/logs — Execution logs
• GET /agents/{id}/messages — List messages
• POST /agents/{id}/messages — Send message to agent
• GET /agents/{id}/clarifications — Pending clarification requests
• POST /agents/{id}/clarifications/{cid}/answer — Answer a clarification

Agent Channel (/agent-channel)

Message queue between Aira and AI agent containers:

• GET /agent-channel/{id}/messages — Poll pending messages
• POST /agent-channel/{id}/reply — Agent sends a reply
• POST /agent-channel/{id}/task/{tid}/accept — Report task acceptance
• POST /agent-channel/{id}/task/{tid}/status — Report task status
• POST /agent-channel/{id}/task/{tid}/pr — Report PR creation
• POST /agent-channel/{id}/task/{tid}/clarification — Submit clarification request
• POST /agent-channel/{id}/heartbeat — Agent heartbeat
• POST /agent-channel/{id}/log — Log execution action

Chat (/chat)

Conversational interface. Messages go through the full LangGraph pipeline.

Chat Sessions (/chat/sessions)

Session management for chat conversations. Create, list, update, archive.

Onboarding (/onboarding)

Multi-stage onboarding pipeline:

• POST /onboarding/pipeline/start — Start onboarding pipeline with idempotency key
• GET /onboarding/pipeline — Get active pipeline
• GET /onboarding/pipeline/events — Stream pipeline events (SSE)
• POST /onboarding/pipeline/action — Control pipeline (pause/resume/cancel/retry stage)
• POST /onboarding/pipeline/prd-edit — Submit PRD owner edit and trigger regeneration
• POST /onboarding/pipeline/team-member — Add team member via onboarding flow
• POST /onboarding/stream-token — Request stream token for direct SSE access

Reports (/reports)

AI-generated management reports:

• POST /reports/sprint — Sprint report
• POST /reports/standup — Daily standup
• POST /reports/retro — Retrospective
• POST /reports/forecast — Delivery forecast
• POST /reports/risk-assessment — Risk assessment
• POST /reports/pdf — PDF export (streaming)

Stakeholder (/stakeholder)

Executive-facing intelligence:

• POST /stakeholder/ask — Ask a stakeholder question (natural language)
• GET /stakeholder/health — Project health summary
• GET /stakeholder/forecast — Budget and timeline forecast
• GET /stakeholder/risks — Risk assessment

PRD (/prd)

Product Requirements Document:

• POST /prd/generate — Generate/regenerate PRD with SSE streaming
• GET /prd — Get current PRD
• POST /prd/quality/assess — Quality assessment with SSE streaming
• POST /prd/quality/status — Get quality assessment status

Roadmap (/roadmap)

Roadmap view data, timeline management, and what-if scenarios.

Quality (/quality)

Quality assessment results. List assessments, get specific assessment details.

Costs (/costs)

LLM usage tracking:

• GET /costs — Usage summary
• GET /costs/daily — Daily cost breakdown
• GET /costs/budget — Budget status
• PUT /costs/budget — Update budget limits
• GET /costs/optimize — Optimization suggestions

Dashboard (/dashboard)

Summary statistics: counts, sprint progress, team load.

Pulse (/pulse)

Attention items from static rules, AI review, and heartbeat checks:

• GET /pulse/actions — Get current pulse actions
• POST /pulse/actions/generate — Force-generate fresh AI pulse actions
• POST /pulse/actions/{id}/dismiss — Dismiss a pulse action

Heartbeat (/heartbeat)

Custom monitoring items. Add, list, deactivate heartbeat items.

Activity (/activity)

Project activity log:

• GET /activity — List activity entries
• POST /activity/stream/token — Request SSE stream token
• GET /activity/stream — Live activity stream (SSE)
• GET /activity/stats — Activity statistics
• GET /activity/search — Search activity entries

Events (/events)

Append-only audit event log:

• GET /events — List events
• GET /events/timeline — Event timeline
• GET /events/entity/{type}/{id} — Entity history
• POST /events/{id}/revert — Revert an event

Notifications (/notifications)

User notification management:

• GET /notifications — List notifications
• GET /notifications/unread — Unread count
• PATCH /notifications/{id} — Mark as read
• GET /notifications/preferences — Notification preferences
• PATCH /notifications/preferences — Update preferences
• POST /notifications/test — Send test notification

Issues (/projects/{id}/issues)

Issue tracking: CRUD for project issues with status and priority management.

Pull Requests (/pull-requests)

PR automation and tracking:

• GET /tasks/{id}/pull-requests — List linked PRs for a task
• POST /tasks/{id}/pull-requests — Link a PR to a task
• POST /pull-requests/sync — Manual PR sync from repositories
• POST /pull-requests/processing/{id}/retry — Retry failed PR processing

Integrations (/integrations)

GitHub, Jira, Slack, Bitbucket, Telegram connection management. Each provider has its own OAuth sub-routes.

• GET /projects/{id}/integrations — List configured integrations
• POST /projects/{id}/integrations/{id}/test — Test integration credentials
• Provider-specific: GitHub OAuth + repo analysis, Bitbucket OAuth + workspace, Jira OAuth, Slack OAuth + event webhook, Telegram webhook

Communication (/communication)

Slack Q&A relay:

• POST /communication/ask — Ask a question to a team member via Slack
• GET /communication/pending — List pending questions
• GET /communication/history — Q&A history
• Team-Slack member mapping management

Invitations (/invitations)

Project invitation management. Create, list, accept invitations.

Billing (/billing)

Subscription management and usage tracking.

LLM (/llm)

Available model listing:

• GET /llm/models — All supported models
• GET /llm/models/available — Models with configured API keys

MCP (/mcp)

Model Context Protocol:

• POST /mcp/bootstrap-token — Issue bootstrap token
• GET /mcp/tools/catalog — MCP tool catalog
• POST /mcp/project-key — Exchange bootstrap token for project API key
• OAuth endpoints: /.well-known/openid-configuration, /mcp/oauth/authorize, /mcp/oauth/token

Webhooks (/webhooks)

Inbound webhook receivers for GitHub, Jira, Slack, Bitbucket, and Telegram events.

Admin (/admin)

System administration with 7 sub-modules:

Miscellaneous

SSE streaming pattern

Long-running operations use Server-Sent Events for real-time progress:

Consuming an SSE stream

const response = await fetch('/api/v1/features/generate/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <token>',
    'X-Project-Id': '<project_id>'
  },
  body: JSON.stringify({ insight_ids: ['...'] })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const blocks = buffer.split('\n\n');
  buffer = blocks.pop();

  for (const block of blocks) {
    const eventMatch = block.match(/^event: (.+)$/m);
    const dataMatch = block.match(/^data: (.+)$/m);
    if (!eventMatch || !dataMatch) continue;

    const eventType = eventMatch[1];
    const data = JSON.parse(dataMatch[1]);

    switch (eventType) {
      case 'feature':
      case 'insight':
      case 'task':
        // Item generated — render it
        break;
      case 'progress':
        // Processing update
        break;
      case 'done':
        // Generation complete
        return;
      case 'error':
        // Something went wrong
        return;
    }
  }
}

Event types

Backpressure

• new_atom_ids and derived_artifact_ids are coalesced in 250ms windows
• Target: 10 events/second max per stream under heavy load
• Events include a monotonic seq for ordering and dedup

SSE endpoints

The following operations support SSE streaming:

OpenAPI docs

Friendly docs-site aliases:

• Swagger UI: /docs/api/swagger
• ReDoc: /docs/api/redoc

Direct proxied API docs URLs:

• Swagger UI: /api/v1/swagger
• ReDoc: /api/v1/redoc
• OpenAPI JSON: /api/v1/openapi.json

For direct local backend access (without frontend proxy):

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

The /api/v1/docs endpoint is a separate authenticated internal docs route, not the FastAPI Swagger UI.