Requests let workspace members propose source additions or removals and collect reviews before the change takes effect. You create a request in DRAFT, attach the proposed changes, submit it for review, then reviewers approve, request changes, or reject.
Prerequisites
- An AiQL API key in the
AIQL_API_KEY environment variable
- A workspace ID (see Quickstart to create one)
- At least one source (document) ID in that workspace to target with a change
Create a request
Create a request with a title. It starts in DRAFT so you can still edit it and add changes.
The response includes an id and status of DRAFT. Save the request ID for the steps below.
Add changes
While the request is in DRAFT, attach the sources you want to add or remove. type is either SOURCE_ADD or SOURCE_REMOVE.
Remove a change the same way while still in DRAFT:
Content edits (title, description, labels, assignees) and change add/remove are only allowed while the request is in DRAFT. Editing after submit returns 409 Conflict.
Submit for review
When the request is ready, the author transitions it to OPEN. Only the author can call this.
The request moves to OPEN and sets opened_at. See Request status lifecycle for every allowed transition.
Start a review
A reviewer creates (or resumes) a draft review on an open request. Calling create again while a draft already exists for that reviewer resumes the draft instead of creating a duplicate.
Draft reviews are private to the reviewer. Other members only see a review after it is submitted.
Add a comment while working through the review:
Submit the review
Submit with approve, request_changes, or reject. This moves the review out of DRAFT and advances the parent request with the same event.
Submitted reviews are immutable. See Review status lifecycle for the review state machine.
Any transition that is not allowed returns 409 Conflict.
Reopen after feedback
If a reviewer requested changes or rejected the request, the author can reopen it:
reopen moves CHANGES_REQUESTED or REJECTED back to OPEN and refreshes opened_at.
List requests
List every request in the workspace, or only the ones you authored or are assigned to.
role accepts any (default), author, or assignee. Results are returned a page at a time — see Pagination.
Get a request with reviews
The detail response includes changes and visible reviews (other reviewers’ drafts are hidden).
Assign reviewers with assignee_ids when you create or update a draft request so they can find it under /requests/mine?role=assignee.
