# 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](/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](/mothership-overview) 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

```bash
aura daemon start --http 127.0.0.1:7420
```

Check:

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

A running daemon returns:

```json
{
  "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:

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

Provision tokens with:

```bash
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](/slack-discord-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

```bash
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

```bash
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

```bash
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

```bash
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:

```json
{
  "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:

```json
{
  "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:

```bash
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:**

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

**Prove failure rate per branch:**

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

**Open impacts per team:**

```bash
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:

```bash
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](/slack-discord-webhooks) | ~100ms | Best-effort retry | Chat notifications, simple sinks |
| SSE (`/v1/events?subscribe=true`) | &lt;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](/mcp-server) — the higher-level tool surface over the same data.
- [Slack / Discord webhooks](/slack-discord-webhooks) — push instead of pull.
- [Custom plugins](/custom-plugins) — in-process access to the same APIs.
- [Mothership overview](/mothership-overview) — the team-deployment target.