API Reference

Aira's backend exposes a REST API under /api/v1 with over 60 route modules and roughly 500 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.
• POST /sources/{id}/analyze/stream — Stream insights extraction 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/merge-ops/{id}/approve — Approve/reject a merge operation
• POST /knowledge/contradictions/rebuild-hard-replace — Hard-replace contradiction history and rebuild from active atoms

Insights (/insights)

User-facing projection of knowledge atoms. List, filter, create, update. (Citations are returned inline by the synthesize endpoint; there is no dedicated citations route, and insights are dismissed/resurrected rather than hard-deleted.)

Key endpoints:

• POST /insights/synthesize — Cross-source pattern synthesis (returns a narrative synthesis string plus a list of cited atom IDs — {"synthesis": ..., "citations": [...]} — not insight objects)
• POST /insights/{id}/verify — Apply HITL verification to the insight's linked atoms
• POST /insights/merge — Merge duplicate insights
• POST /insights/{id}/resurrect — Resurrect a dismissed insight and reactivate linked atoms

Features (/features)

Feature CRUD plus AI generation:

• POST /features/generate/stream — Iterative feature generation with SSE streaming
• POST /features/{id}/breakdown — Break down a feature into tasks
• GET /features/quality/stream — Project-wide feature 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/assess — Assess whether a workload rebalance is needed
• POST /tasks/rebalance — Rebalance workload across the team (preview)
• POST /tasks/rebalance/{proposal_id}/approve — Approve or reject a rebalance proposal
• POST /tasks/rebalance/apply — Apply a rebalance plan

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/analyze-changes — Ingest objective task/PR signals and refresh daily member metrics
• GET /team-ledger/metrics/daily — Daily objective member metrics
• POST /team-ledger/testimony/analyze-changes — Ingest restricted testimony signals
• GET /team-ledger/testimony/themes — Extracted testimony themes
• GET /team-ledger/contradictions — Team-dynamics contradictions
• GET /team-ledger/escalations — List escalation cases (admin-only)
• GET /team-ledger/policy/fairness/active — Active fairness policy version
• GET /team-ledger/policy/fairness/versions — Fairness policy version history
• GET /team-ledger/rebalance/decisions/{decision_id} — Rebalance decision detail
• GET /team-ledger/rebalance/{proposal_id}/candidates — Candidate rebalance 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/pipelines/start — Start or resume onboarding pipeline with idempotency key
• GET /onboarding/pipelines/active — Get active pipeline for the current project
• GET /onboarding/pipelines/{id} — Get a specific pipeline
• GET /onboarding/pipelines/{id}/stream — Stream pipeline events (SSE)
• POST /onboarding/pipelines/{id}/stream/session — Mint a short-lived stream-session token for direct SSE access
• POST /onboarding/pipelines/{id}/actions — Control pipeline (pause/resume/cancel/retry stage)
• POST /onboarding/pipelines/{id}/prd-edits — Submit PRD owner edit and trigger regeneration
• POST /onboarding/pipelines/{id}/team-members — Add team member via onboarding flow

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/risks — Risk assessment
• POST /reports/generate-pdf — PDF management report (streaming)

Stakeholder (/stakeholder)

Executive-facing intelligence:

• POST /stakeholder/ask — Ask a stakeholder question (natural language)
• GET /stakeholder/dashboard — Stakeholder dashboard
• GET /stakeholder/questions — Question history
• GET /stakeholder/schedules — List scheduled reports
• POST /stakeholder/reports — Save a report to history
• POST /stakeholder/schedule — Schedule a recurring report

PRD (/projects/{id}/prd)

Product Requirements Document (PRD routes are nested under the project):

• POST /projects/{id}/prd/generate/stream — Generate/regenerate PRD with SSE streaming
• GET /projects/{id}/prd — Get current PRD
• GET /projects/{id}/prd/quality/stream — Quality assessment with SSE streaming
• POST /projects/{id}/prd/quality/cancel — Cancel a running quality assessment

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/count — Unread count
• PUT /notifications/{id}/read — Mark one as read
• PUT /notifications/read-all — Mark all as read
• GET /notifications/preferences — Notification preferences
• PUT /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 /integrations/github/sync-prs — Sync PRs from connected GitHub repos
• POST /integrations/bitbucket/sync-prs — Sync PRs from connected Bitbucket repos

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 one-time MCP bootstrap token
• GET /mcp/tools/catalog — MCP tool catalog
• POST /mcp/bootstrap/exchange — Exchange bootstrap token for a project API key
• OAuth endpoints: /.well-known/oauth-authorization-server, /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

The app uses FastAPI's default documentation surface (no custom docs_url/redoc_url overrides), served at the server root:

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

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