Reference
Reference overview
Aurora's external API is intentionally compact. That keeps the surface understandable while still covering the execution flows most clients need: discovery, projects, issues, durable comments, and meetings.
| Convention | Details |
|---|---|
| Base URL | https://www.auroraworkos.com |
| Auth | Authorization: Bearer aurora_pat_... (preferred) |
| Content type | application/json |
| Workspace scope | Every request resolves only inside the token workspace |
| Create safety | Use Idempotency-Key on create routes |
| Pagination | Use limit and cursor on supported list routes |
Conventions
Request conventions
These rules apply across the reference surface.
Discovery first
Treat GET /api/external as your entry point, then resolve teams, users, and statuses before any dependent write.
Key-friendly writes
Prefer teamKey, projectKey, issueKey, and statusKey when you can. Use opaque ids when you have already resolved them.
Auth boundary
API tokens and OAuth connector access work on the external API only. They do not create a browser session and they cannot be used on internal app pages or customer-shell APIs.
Resource family
Discovery
Start every new client with discovery so you can resolve teams, statuses, users, and workspace capabilities before you mutate anything.
| Operation | Purpose | Notes |
|---|---|---|
| GET /api/external | Discover token identity, workspace metadata, endpoint map, and capability flags. | Call this first when wiring a new client or validating a token. |
| GET /api/external/teams | List teams visible to the token workspace and return defaultTeamId. | Use this to resolve teamId and teamKey pairs. |
| GET /api/external/users | List workspace members plus automation-agent queue identities derived from API token names. | Use for ownerId, reporterId, human assigneeId, and automation assignment. |
| GET /api/external/statuses | List statuses for the first workspace team or a specific team by id/key. | Pass teamId or teamKey when status resolution needs to be explicit. |
Resource family
Projects
Project routes support both opaque ids and stable key-based lookups so operators and agents can work in more human-readable terms.
| Operation | Purpose | Notes |
|---|---|---|
| GET /api/external/projects | List workspace projects, optionally filtered by team and paginated with limit/cursor. | Supports teamId, teamKey, limit, and cursor. |
| GET /api/external/projects/{projectId} | Fetch one project by opaque project id. | Use when you already persisted a project id from a previous read. |
| GET /api/external/projects/by-key/{teamKey}/{projectKey} | Fetch one project by stable natural key. | Preferred for agent flows that already know team and project keys. |
| POST /api/external/projects | Create a project with optional explicit team and owner resolution. | Supports Idempotency-Key and will derive a project key when omitted. |
| PATCH /api/external/projects/{projectId} | Update project name, key, description, team, or owner. | Team moves are blocked when the project still contains issues. |
Resource family
Issues
Issue routes are designed for triage, automation queue pickup, and stable lookup by issue key or project key.
| Operation | Purpose | Notes |
|---|---|---|
| GET /api/external/issues | List issues by project, team, assignee, status, query text, and pagination cursor. | Supports assignedToMe for automation-queue polling. |
| GET /api/external/issues/{issueId} | Fetch one issue by opaque issue id. | Useful after you already resolved an issue in an earlier API call. |
| GET /api/external/issues/by-key/{issueKey} | Fetch one issue by stable issue key. | Preferred when you already have an Aurora issue key from chat or another system. |
| POST /api/external/issues | Create an issue with project, status, assignee, reporter, labels, and date fields. | Supports Idempotency-Key and accepts project/team natural keys. |
| PATCH /api/external/issues/{issueId} | Update status, assignment, project, dates, priority, and other mutable issue fields. | Use structured error codes to recover from stale status or project references. |
Resource family
Meetings and agenda workflows
Aurora's external API also covers structured meeting execution so agenda capture and task conversion can stay inside the same automation boundary.
| Operation | Purpose | Notes |
|---|---|---|
| GET /api/external/meetings | List meetings with team, project, type, recurrence, archive, search, and pagination filters. | Supports teamId/teamKey, projectId/projectKey, type, recurrenceType, archived, view=archived, q, limit, and cursor. |
| POST /api/external/meetings | Create a meeting with optional team, project, schedule, and workflow metadata. | Supports Idempotency-Key. |
| GET|PATCH|DELETE /api/external/meetings/{meetingId} | Read, update, or delete a specific meeting. | Use PATCH for meeting-level metadata and DELETE for cleanup workflows. |
| GET /api/external/meetings/settings | Load meeting workflow settings and write external owner presets or agenda statuses through child routes. | Use external-users and agenda-statuses child routes for POST, PATCH, and DELETE writes. |
| POST /api/external/meetings/settings/external-users | Create a reusable external agenda owner preset. | Presets copy external owner details onto agenda items; they do not create user accounts. |
| PATCH|DELETE /api/external/meetings/settings/external-users/{presetId} | Update or delete a reusable external agenda owner preset. | Existing agenda item owner copies are not retroactively changed by preset edits. |
| POST /api/external/meetings/settings/agenda-statuses | Create a workspace agenda item status. | Custom statuses can be used through agenda item statusId. |
| PATCH|DELETE /api/external/meetings/settings/agenda-statuses/{statusId} | Update or delete a workspace agenda item status. | System statuses stay protected; use convert for conversion-safe status changes. |
| POST /api/external/meetings/{meetingId}/links | Attach meeting-level related work. | Targets can be issue, project, discussion_topic, or agenda_item; duplicate links collapse. |
| DELETE /api/external/meetings/{meetingId}/links/{linkId} | Remove a meeting-level work link. | The link and target must belong to the token workspace. |
| GET|POST /api/external/meetings/{meetingId}/agenda-items | List agenda items or create a new one inside a meeting. | Agenda items support startDate and checkInDate. |
| GET|PATCH|DELETE /api/external/meetings/{meetingId}/agenda-items/{agendaItemId} | Read, update, or delete a specific agenda item. | Use statusId for custom statuses; checkInDate is the theoretical finish date. |
| GET|POST /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/owners | List or add agenda item owners. | Supports both internal and reusable external owner presets. |
| DELETE /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/owners/{ownerId} | Remove an owner from an agenda item. | Useful for cleanup during agenda rebalancing workflows. |
| POST /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/links | Attach related work directly to an agenda item. | Targets can be issue, project, discussion_topic, or agenda_item; targetKey works for issue and project targets. |
| DELETE /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/links/{linkId} | Remove an agenda item work link. | Use when a linked issue, project, topic, or agenda reference is no longer relevant. |
| POST /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/notes/publish | Publish agenda item notes to a linked issue comment. | Uses issueId/issueKey when supplied or falls back to converted, linked, or task-created issues. |
| POST /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/convert | Convert an agenda item into an issue and mark it converted. | Agenda-idempotent; omitted dueDate falls back to the agenda checkInDate. |
| POST /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/tasks | Create related issues from an agenda item without marking it converted. | Supports Idempotency-Key; omitted dueDate falls back to the agenda checkInDate. |
Resource family
Issue comments
Comments are first-class external resources so human operators and automation can leave durable audit trails on the same issue thread.