Developer API Guide
Build Aurora clients that behave well under retries, ambiguity, and agent loops.
This guide summarizes the integration patterns that matter most when your client is not just a human clicking around, but an automated system or AI agent that has to discover state, retry safely, and recover from partial context.
Discovery before mutation
Resolve workspace structure from the discovery endpoints before attempting writes.
Idempotent create flows
Create requests accept `Idempotency-Key` so retries from agents do not duplicate state.
Stable key routing
Project and issue lookup routes support natural keys, which are easier for agents to reason about than opaque IDs.
Structured recovery
Errors include a machine code, details payload, and recovery suggestion for programmatic branching.
Recommended agent loop
- 1. Call `GET /api/external` and cache the capability map.
- 2. Load teams, users, and statuses once per workspace token.
- 3. Prefer `teamKey`, `projectKey`, and `issueKey` when generating tasks.
- 4. Send `Idempotency-Key` on every create route.
- 5. Page through large collections using `limit` and `cursor`.
- 6. Branch on structured `code` values instead of parsing human error text.
What this unlocks
- Lower duplicate record risk in repeated runs.
- Cleaner prompts because clients can talk in stable keys instead of ephemeral IDs.
- Less round-trip waste during planning and orchestration loops.
- Programmatic recovery when a team, project, or status reference is stale.
Current production support
The API now supports key lookup routes, idempotent create calls, cursor pagination for projects and issues, and structured error payloads intended for automation clients.