fn get(numbers: array)
Fetch one or more issues with full ripple bodies, events, lifecycle entries and relationships — what `swamp issue get` only counts.
| Argument | Type | Required | Description |
|---|
| numbers | array | yes | Issue numbers. Fanned out in one execution rather than one run per issue. |
fn search(q?: string, source?: string, author?: string, limit?: number, offset?: number, name?: string)
Search and list issues. Only issues visible to this key are returned.
| Argument | Type | Required | Description |
|---|
| q? | string | no | Free-text query. |
| source? | string | no | Filing source, e.g. `agent`. |
| author? | string | no | Author username. |
| limit? | number | no | |
| offset? | number | no | |
| name? | string | no | Instance name for the result. Defaults to `search`, so the latest search overwrites the last. |
fn create(title: string, body: string, source?: string)
File an issue. `platform` is admin-only; non-admins file feature, bug or security.
| Argument | Type | Required | Description |
|---|
| title | string | yes | |
| body | string | yes | Markdown. |
| source? | string | no | Filing source, 1-64 word characters, e.g. `agent`. |
fn update(title?: string, body?: string, source?: string, assignees?: array, commentLocked?: boolean, githubPrUrl?: string, githubPrNumber?: number, blocked?: boolean, blockedReason?: string, resolvedInVersion?: string)
Patch an issue. Authors may change title, body, and status to open/closed; admins may change everything, and status verbs drive transitions (triaged, in_progress, shipped). An invalid transition is a 422.
| Argument | Type | Required | Description |
|---|
| title? | string | no | |
| body? | string | no | |
| source? | string | no | Admin only. |
| assignees? | array | no | User ids, not usernames. Admin only. |
| commentLocked? | boolean | no | Admin only. |
| githubPrUrl? | string | no | Admin only. |
| githubPrNumber? | number | no | Admin only. |
| blocked? | boolean | no | Admin only. |
| blockedReason? | string | no | Admin only. |
| resolvedInVersion? | string | no | Admin only. null clears it. |
fn delete(confirm: literal)
Hard-delete an issue and everything hanging off it. Admin only, irreversible — run `get` first and confirm the number. An issue that is already gone succeeds.
| Argument | Type | Required | Description |
|---|
| confirm | literal | yes | Must be true. There is no soft delete and no undo. |
fn ripple(body: string)
Post a ripple (comment) on an issue. Markdown; profanity is rejected with a 422 naming the flagged words.
| Argument | Type | Required | Description |
|---|
| body | string | yes | |
fn editRipple(commentId: string, body: string)
Replace a ripple's body. Author or admin only.
| Argument | Type | Required | Description |
|---|
| commentId | string | yes | |
| body | string | yes | |
fn deleteRipple(commentId: string)
Delete a ripple. Author or admin only.
| Argument | Type | Required | Description |
|---|
| commentId | string | yes | |
fn relationships()
List an issue's relationships, each marked `incoming` or `outgoing`. Carries the relationship ids `unrelate` needs.
fn relate(links: array)
Link an issue to others — e.g. wire an epic to its children with `parent_of`. Fans out over every link in one execution.
| Argument | Type | Required | Description |
|---|
| links | array | yes | |
fn unrelate(relationshipId: string)
Remove one relationship by id (from `relationships`). Removing the last blocker unblocks the issue.
| Argument | Type | Required | Description |
|---|
| relationshipId | string | yes | |
fn lifecycle(step: string, summary: string, emoji: string, payload?: record, body?: string, isVerbose?: boolean)
Append a structured triage/lifecycle entry. Admin only — use it only when deliberately driving an issue's lifecycle, never as a comment.
| Argument | Type | Required | Description |
|---|
| step | string | yes | |
| summary | string | yes | |
| emoji | string | yes | |
| payload? | record | no | |
| body? | string | no | |
| isVerbose? | boolean | no | |
fn assignees()
List operatives eligible for assignment, with the user ids `update --assignees` takes. Admin only.
Resources
issue(infinite)— One issue with full ripple bodies, events, lifecycle entries and relationships
search(7d)— One page of issue search results
ripple(infinite)— A ripple (comment) as the Lab stored it
relationships(infinite)— An issue's relationships, each marked incoming or outgoing
lifecycleEntry(infinite)— A lifecycle (triage trail) entry as appended
assignees(1d)— Operatives eligible for issue assignment