Reference
Reference overview
Aurora's external API covers workspace discovery and the execution workflows used by people and agents: projects, issues, relationships, sub-tasks, milestones, linked attachments, meetings, and discussions.
| 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. |
| GET /api/external/tags | Discover managed tags plus issue and project-linked agenda tag usage. | Returns issueCount, agendaItemCount, usageCount, projectIds, and managedScopes within token project access. |
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
Issue containers and milestones
Issue containers provide epic-like grouping, while container milestones model non-task checkpoints with owners, status, dates, tags, comments, and activity history.
| Operation | Purpose | Notes |
|---|---|---|
| GET /api/external/issue-containers | Discover project issue containers/epics with schedule and issue-count metadata. | Supports projectId, projectKey, teamId, teamKey, q, and archived=true. |
| GET /api/external/issue-container-milestones | List container milestones by project, epic/container, owner, status, search text, and pagination cursor. | Automation agents only see milestones in projects where their token has project access. |
| POST /api/external/issue-container-milestones | Create a non-task checkpoint milestone inside an issue container. | Milestones support ownerId, planned/at-risk/blocked/complete status, start/due dates, order, and tags. |
| GET|PATCH|DELETE /api/external/issue-container-milestones/{milestoneId} | Read, update, or delete a specific container milestone. | Patch supports clearing ownerId, startDate, and dueDate with null values. |
| GET|POST /api/external/issue-container-milestones/{milestoneId}/comments | Read or add durable comments on a container milestone. | PAT comments are attributed to the token queue through authorApiTokenName. |
Resource family
Issue relationships, attachments, and sub-tasks
Issue utility routes cover mainline relationships, link-backed attachments, and lighter child work that remains under one parent issue.
| Operation | Purpose | Notes |
|---|---|---|
| POST|DELETE /api/external/issues/{issueId}/links | Create or remove a blocks, blocked-by, or related relationship between mainline issues. | DELETE receives linkId in the JSON body. Relationship updates keep the inverse issue link consistent. |
| GET|POST /api/external/issues/{issueId}/attachments | List or append http/https link-backed issue attachments. | Binary upload/download and workspace file repository operations still require a browser app session. |
| GET|POST /api/external/issues/{issueId}/subtasks | List or create sub-tasks under a parent issue. | Sub-tasks inherit reporter, project, and epic/container context. The workflow and parent issue must allow sub-tasks. |
| GET|PATCH|DELETE /api/external/issues/{issueId}/subtasks/{subtaskId} | Read, update, or delete a specific sub-task. | Supported statuses are to-do, in-progress, and done. Schedules and assignment remain sub-task specific. |
| POST|DELETE /api/external/issues/{issueId}/subtasks/{subtaskId}/links | Create or remove sibling-only sub-task dependencies and related links. | A sub-task relationship cannot cross parent issues; use the main issue-link route for cross-issue work. |
| POST /api/external/issues/{issueId}/subtasks/{subtaskId}/promote | Promote a sub-task into a mainline issue. | Requires an explicit compatible target status mapping and marks the source sub-task as migrated. |
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. | Set agendaGroupId to place the item in a meeting agenda group. Agenda tags inherit the meeting project when sourceProjectId is omitted; explicit null keeps a tag agenda-only. |
| GET|POST|PATCH /api/external/meetings/{meetingId}/agenda-groups | List, create, or reorder meeting agenda groups. | POST supports Idempotency-Key. PATCH requires the complete ordered agendaGroupIds list. Reordering groups moves their agenda items as blocks and preserves item order within each group. |
| PATCH|DELETE /api/external/meetings/{meetingId}/agenda-groups/{agendaGroupId} | Rename, describe, or delete an agenda group. | Deleting a group leaves its agenda items in the meeting as ungrouped items. |
| GET /api/external/meetings/{meetingId}/agenda-tags | Discover workspace and project-linked tag suggestions for the meeting agenda. | Includes managed presets, issue usage, and existing project-linked agenda usage visible to the token. |
| GET|PATCH|DELETE /api/external/meetings/{meetingId}/agenda-items/{agendaItemId} | Read, update, or delete a specific agenda item. | Set agendaGroupId to a group in the same meeting, or null to ungroup it. Tag replacement uses meeting-project inference unless sourceProjectId is explicit; use statusId for custom statuses. |
| GET|POST /api/external/meetings/{meetingId}/agenda-items/{agendaItemId}/attachments | List or append http/https link-backed agenda item attachments. | Binary upload/download remains a browser app-session operation; external clients can preserve accessible links. |
| 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
Stakeholder discussions
Discussion routes are scoped to the effective Aurora user and only expose groups the owner has left visible to external API clients.
| Operation | Purpose | Notes |
|---|---|---|
| GET|POST /api/external/discussion | List API-enabled stakeholder groups visible to the caller or create a new owned group. | Responses include visibility metadata; zero results do not prove workspace-wide absence. |
| PATCH /api/external/discussion/groups/{groupId} | Rename an owned API-visible stakeholder group. | Groups marked private from API are not readable or writable through external routes. |
| GET|POST /api/external/discussion/topics | Search or create discussion topics in API-enabled stakeholder groups. | The q filter matches visible topic titles, descriptions, and stakeholder group names. |
| GET|PATCH /api/external/discussion/topics/{topicId} | Read or update an API-visible discussion topic. | Patch supports title, description, status, and links to issues, projects, or agenda items. |
| POST /api/external/discussion/topics/{topicId}/convert | Convert an API-visible discussion topic into an issue. | Supports Idempotency-Key and returns existing converted work on repeat calls. |
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.