Aura HTTP API Reference

Programmatic access to intents, impacts, messages, and snapshots.

Overview

Everything Aura knows about your codebase is available over a local HTTP API. The MCP server is a higher-level surface aimed at AI agents; the HTTP API is the raw kernel. Use it to build dashboards, custom CI steps, auditing pipelines, or in-house tools.

Two deployment modes:

1. Local. aura daemon exposes the API on a Unix socket (~/.aura/daemon.sock) and optionally on localhost:7420. For single-developer tooling.
2. Team. The Mothership exposes the same API over HTTPS for team-wide queries. Auth is required.

The API is resource-oriented, JSON-only, and versioned. The OpenAPI specification is served at /openapi.json on any running Aura daemon or mothership, and is also published at https://aura.build/openapi.json for the current release.

Setup

Local daemon

aura daemon start --http 127.0.0.1:7420

Check:

curl http://127.0.0.1:7420/v1/status

A running daemon returns:

{
  "version": "0.14.1",
  "repo": "/Users/ashiq/code/my-app",
  "branch": "feat/login",
  "session": "ses_01HW3K...",
  "strict_mode": true,
  "team": { "connected": false }
}

Mothership

For team-wide queries, hit your mothership URL with a bearer token:

curl https://team.example.com/v1/status \
  -H "Authorization: Bearer $AURA_TEAM_TOKEN"

Provision tokens with:

aura team token create --scope read_intents,write_messages

Authentication

Local requests on the Unix socket require no auth. HTTP requests on localhost accept a short-lived token printed by aura daemon token.

Mothership requests require Authorization: Bearer <token>. Tokens have scopes:

| Scope | Grants | |-------|--------| | read_intents | GET on /intents, /intents/{id} | | write_intents | POST on /intents | | read_impacts | GET on /impacts | | write_impacts | PATCH resolve impacts | | read_messages | GET on /messages | | write_messages | POST on /messages | | read_snapshots | GET on /snapshots | | admin | Everything, including /admin/*. |

Tokens are rotatable (aura team token rotate <id>) and revocable (aura team token revoke <id>). The mothership enforces scopes server-side.

Endpoints

The API groups resources by category. Full paths, shapes, and query parameters are in the OpenAPI spec; this page covers the categories and representative shapes.

Intents

• GET /v1/intents — list intents. Query: branch, author, since, ticket, limit, cursor.
• GET /v1/intents/{id} — fetch a single intent with full node diff.
• POST /v1/intents — log an intent (equivalent to aura_log_intent).
• GET /v1/intents/{id}/nodes — AST nodes touched.

Sample intent object:

{
  "id": "itn_01HW3K9Z4X7P2Q8R",
  "repo": "naridon-inc/aura",
  "branch": "feat/login-refresh",
  "author": { "id": "ashiq", "name": "Ashiq" },
  "summary": "Refactor retry_logic to use exponential backoff",
  "created_at": "2026-04-21T14:23:09Z",
  "commit_sha": "abc1234",
  "nodes_changed": 3,
  "nodes_added": 1,
  "nodes_deleted": 0,
  "tickets": [{ "system": "linear", "id": "ENG-1421" }],
  "prove_goals": [
    { "goal": "Retries respect Retry-After header", "result": "pass" }
  ]
}

Impacts

Cross-branch impact alerts — what changed on another branch that affects yours.

• GET /v1/impacts — list open alerts. Query: branch, severity, status.
• GET /v1/impacts/{id} — single alert with before/after node snapshots.
• PATCH /v1/impacts/{id} — mark resolved, snoozed, or dismissed.

Sample impact:

{
  "id": "imp_01HW3P4K",
  "your_branch": "feat/login-refresh",
  "other_branch": "feat/session-model",
  "function": "auth::Session::refresh",
  "change": "signature_changed",
  "severity": "warning",
  "status": "open",
  "detected_at": "2026-04-21T13:10:02Z"
}

Messages

Team-to-team and agent-to-agent messaging.

• GET /v1/messages — list messages. Query: channel (team | sentinel), since, unread_only.
• POST /v1/messages — post a message.
• PATCH /v1/messages/{id} — mark read.

Sample:

{
  "id": "msg_01HW3Q...",
  "channel": "team",
  "from": { "id": "jamie", "kind": "human" },
  "to":   { "kind": "broadcast" },
  "body": "Heads up — refactoring billing::invoice for the next hour.",
  "created_at": "2026-04-21T14:01:00Z",
  "read_by": ["ashiq"]
}

Snapshots

• GET /v1/snapshots — list snapshots. Query: file, since.
• GET /v1/snapshots/{id} — snapshot metadata.
• GET /v1/snapshots/{id}/content — raw content (binary, respects Accept header).
• POST /v1/snapshots — create a snapshot for a file path.

Zones

• GET /v1/zones — active zone claims.
• POST /v1/zones — claim a zone.
• DELETE /v1/zones/{id} — release.

Prove

• POST /v1/prove — synchronously run a Prove goal.
• GET /v1/prove/history — past Prove results.

Events (streaming)

• GET /v1/events?subscribe=true — Server-Sent Events stream. Same topics as webhooks (intent.logged, prove.failed, etc.).

Sample SSE frame:

event: intent.logged
data: {"event_id":"evt_01HW...","data":{"intent_id":"itn_01HW...", ...}}

Team and status

• GET /v1/status — daemon health, session, sync state.
• GET /v1/team/members — team roster (mothership only).
• GET /v1/team/sync — pending pushes/pulls.

Examples

List recent intents for a branch

curl -s http://127.0.0.1:7420/v1/intents?branch=feat/login&limit=10 \
  | jq '.data[] | {id, summary, nodes_changed}'

Post an intent from a script

curl -s -X POST http://127.0.0.1:7420/v1/intents \
  -H 'Content-Type: application/json' \
  -d '{
    "summary": "Port auth config loader to new schema",
    "tickets": [{"system": "linear", "id": "ENG-1500"}]
  }'

Stream events into a log pipeline

curl -N https://team.example.com/v1/events?subscribe=true \
  -H "Authorization: Bearer $AURA_TEAM_TOKEN" \
  | while read -r line; do
      echo "$line" | your-log-forwarder
    done

Resolve an impact after fixing it

curl -X PATCH https://team.example.com/v1/impacts/imp_01HW3P4K \
  -H "Authorization: Bearer $AURA_TEAM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"status":"resolved","note":"Updated caller to pass ctx"}'

Pagination

List endpoints return:

{
  "data": [ ... ],
  "next_cursor": "eyJvIjoxMjN9",
  "has_more": true
}

Pass ?cursor=<next_cursor> to the same URL to fetch the next page. limit defaults to 50, max 500.

Rate Limits

Local daemon: no limit (it's your machine).

Mothership: per-token, defaulting to 60 req/min with a 10 req/sec burst. Limit headers on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1713700000

429 responses include a Retry-After header.

Errors

Errors are JSON with a stable shape:

{
  "error": {
    "code": "intent_missing_ticket",
    "message": "Intent must reference a ticket (pattern: [A-Z]{2,6}-\\d+)",
    "hint": "Add [ENG-123] to the summary.",
    "request_id": "req_01HW..."
  }
}

Codes are stable across versions; messages may change.

Troubleshooting

Connection refused on localhost:7420. The daemon isn't running, or --http was never enabled. Start with aura daemon start --http 127.0.0.1:7420.

401 unauthorized from mothership. Token expired. Check aura team token list.

403 scope_missing. The token lacks the required scope. Rotate with wider scopes.

OpenAPI spec out of sync. The spec hosted at https://aura.build/openapi.json tracks the latest release. For your pinned version, use /openapi.json on your running daemon.

Large list calls are slow. Add filters (branch, since) to narrow the result set before paginating. Full-scan queries are O(n) over the intent log.

Batch Operations

For bulk work, batch endpoints accept an array and return parallel results:

curl -X POST http://127.0.0.1:7420/v1/intents:batch \
  -H 'Content-Type: application/json' \
  -d '{
    "intents": [
      { "summary": "Fix null check in auth::login [ENG-1]" },
      { "summary": "Update user docs [ENG-2]" }
    ]
  }'

Response is an array of the same length; each element is either { "ok": { intent } } or { "err": { code, message } }. Partial success is the norm — one failed intent does not abort the rest.

Batch endpoints are available for intents, snapshots, and impacts (resolution). They honor idempotency keys per-item.

Building Dashboards

Common dashboard queries, expressed as API calls:

Intent velocity by author over 30 days:

curl "http://127.0.0.1:7420/v1/intents?since=30d&group_by=author"

Prove failure rate per branch:

curl "http://127.0.0.1:7420/v1/prove/history?group_by=branch&aggregate=fail_rate"

Open impacts per team:

curl "https://team.example.com/v1/impacts?status=open&group_by=team" \
  -H "Authorization: Bearer $AURA_TEAM_TOKEN"

All list endpoints support group_by and aggregate (count, sum, avg, fail_rate). For deeper analysis, export to your warehouse via the events stream and run SQL on your own infrastructure — Aura does not aim to be a BI tool.

CORS and Browser Clients

By default, the local daemon does not enable CORS. To build a browser-based dashboard against the local daemon, enable CORS with an explicit origin:

aura daemon start --http 127.0.0.1:7420 --cors 'http://localhost:3000'

The mothership disables CORS by default and recommends running browser clients from the same origin as the API. For cross-origin browser access, configure a reverse proxy with credentials-forwarding.

Versioning and Compatibility

The HTTP API is versioned under /v1. Breaking changes get a new major version; the old version is kept for at least 6 months. Minor and patch versions are additive — new fields, new endpoints, new optional parameters.

The X-Aura-Version response header on every call identifies the daemon or mothership version. Clients can pin to a minimum version with Aura-API-Version: >=1.3 as a request header; older daemons will return 426 Upgrade Required.

Idempotency

Mutating endpoints (POST /v1/intents, POST /v1/snapshots, PATCH /v1/impacts/{id}) accept an Idempotency-Key header. Aura stores the response for 24 hours and replays it verbatim on repeated calls with the same key. Use this for any retry logic in CI or custom tooling — double-posting an intent produces exactly one intent.

Webhooks vs. SSE vs. Polling

Three ways to observe events:

| Method | Latency | Durability | Use case | |--------|---------|------------|----------| | Webhooks | ~100ms | Best-effort retry | Chat notifications, simple sinks | | SSE (/v1/events?subscribe=true) | <50ms | Session-scoped (reconnect replays from cursor) | Dashboards, real-time UIs | | Polling (GET /v1/intents?since=...) | Depends on interval | Fully durable | Compliance exporters, audit log pipelines |

For compliance-grade durability, poll with a persistent cursor. The cursor is monotonic and survives daemon restarts.

SDKs

Official SDKs wrap the API with language-native types, retries, and auth helpers:

• Rust: aura-sdk on crates.io
• TypeScript: @aura/sdk on npm
• Python: aura-sdk on PyPI
• Go: github.com/Naridon-Inc/aura-go

All four are generated from the OpenAPI spec plus hand-written ergonomics. If you prefer to generate your own client, point openapi-generator at /openapi.json.

See Also

• MCP server — the higher-level tool surface over the same data.
• Slack / Discord webhooks — push instead of pull.
• Custom plugins — in-process access to the same APIs.
• Mothership overview — the team-deployment target.