Projects
Projects connect one or more repositories to Jaah: their branches, gate commands, members, environment variables, node groups, MCP links and issue-tracker links. A project's endpoints also cover its release pipeline and history, its merge lane, its project memory, how its deploys reach Jaah, its outcome scan and its Live Cast settings; List merge lane rows across projects reads every merge lane you can view.
List merge lane rows across projects
Returns one page of merge lane rows across every project you may view, newest change first, each with its project, PR, state and failing tests. Narrow it with `project_id` and `state` (`open`: queued, testing or failed; `settled`: merged, superseded or closed); pages with `limit` (up to 100) and `cursor`, sent back unchanged from `next_cursor`.
List projects
Lists the projects the caller may view, up to `limit`: by name, or with `order=activity` most tasks created in the last 30 days first, then by name. With `name`, only the project of exactly that name.
Create project
Connects an existing repository as a new project without adding any files to it; to connect several, send `repos` instead of `repo_url`, each row with its `repo_url` and `integration_branch` and exactly one marked `is_primary`; with neither, the project has no repository and each of its tasks runs in an empty folder instead of a git worktree. With `placement`, which requires the Org Owner or Org Admin role, checks the nodes named (404 for an unknown node or another organization's, 409 for a disabled one) and answers a `placement_warning` when cloning on them would fail, but declares nothing, since a new project runs on every node of its organization. Returns 201 with the project, or 422 naming each bad `repos` row by its index.
Get governance authority for a new project
Returns `may_author_governance`: whether the caller may set branch, gate, stack and push settings on a new project. Creating a project with those fields fails with 403 when it is false.
List pipeline chains
Lists the projects of the caller's organization they may view, each with its stage chain: the projects a pipeline can be copied from. `exclude` leaves out the project being edited and picks its organization.
Delete project
Deletes the project from Jaah, and every task in it, without touching its repository; an Easy Mode project's hosted app goes with it, only when `confirm` is the app's address (422 otherwise). Returns 409 while the project's hosted app is still being set up or one of its worktrees has no node that can address it; otherwise erases its worktrees on their nodes and returns 204 with no body; a system project cannot be deleted (422). Requires the Org Owner or Org Admin role.
Get project
Returns one project the caller may view, with the same fields as each project List projects returns. A project the caller may not view, or another organization's, returns 404.
Update project
Changes the fields sent on a project; null clears an optional field, but null on the name, branch, prefix, gate or stack commands, or push setting returns 422. `repos` replaces the connected repositories as a whole set (a row with `id` is updated, one without is added, any left out is removed); changing branch, gate, stack or push settings, or the primary repository's branch, needs governance authority; changing Run jobs as needs the Org Owner or Org Admin role; connecting a project's first repository or removing its last needs the Org Owner or Org Admin role and permission to both create and delete projects (an empty `repos`, or a null `repo_url`), which stops every task running in one of its git worktrees and queues it again to run in an empty folder. `merge_lane_enabled` turns the project's merge lane on or off; turning it on answers 409 when the organization's plan has no merge lane, and null is a 422; returns the project, or 422 naming each bad `repos` row by its index.
List project environment variables
Lists the project's environment variables, both project defaults and every user's overrides, marking which one wins for the current user. Literal values are returned; a credential-drawn variable names its credential and field, never the secret.
Create project environment variable
Adds an environment variable to the project, as a literal value, drawn from a credential, or a Port (`source` `port`): no value, the node gives each slot a free port, trying `port_preferred` (1024 to 65535) first when set; a Port variable is project-wide only (422 for a personal one, a name Jaah sets on every slot, or a preferred port inside the organization's auto-assign range). A project default requires project edit permission; anyone who can view the project may add their own override. Returns 201 with the variable.
Preview project environment variables
Returns the winning environment variables a worktree for `user_id` (default: the current user) would receive from the project: literal values in full, credential-drawn ones by credential and field only. Variables whose status is not `ok` are not written.
Delete project environment variable
Removes an environment variable. A project default requires project edit permission; only its own user may remove an override. Returns 204 with no body.
Update project environment variable
Changes an environment variable in place, with the same rules as adding one; only a Port variable takes `port_preferred`. A project default requires project edit permission; only its own user may change an override. Returns the variable.
Get gate runs
Lists a project's newest gate runs, at most 20: each run of a step's or a stage's gate list on one subject (`subject_kind` `lane_batch`, `release` or `arrival`, and its `subject_id`), with each gate's state, attempts, plain-text report and link. Requires View on the project.
Get project git reach
Returns whether the caller's own git credentials can push to the project's primary repository: `ok`, `fallback` (another of their credentials is used), `blocked` (with `problem` and `fix_url`) or `unknown`.
Get project governance authority
Returns `may_author_governance`: whether the caller may change the project's integration branch, branch prefix, gate and stack commands, and push setting.
Get Live Cast settings
Returns the project's Live Cast settings: whether it is on, the default (`all` or `none`), the rules, whether it is published and its public URL, evaluation progress, and the organization's allowance and use. Before the first save it shows the defaults and the public address that save will keep. Requires the Org Owner or Org Admin role; 403 when the plan has no Live Cast.
Set Live Cast settings
Saves the project's Live Cast checkbox, default and rules (at most 20, each 1 to 500 characters). Returns 409 while the project is published: unpublish to edit. Requires the Org Owner or Org Admin role; 403 when the plan has no Live Cast.
Publish Live Cast
Publishes the project's Live Cast: freezes the default and rules and records their sha. Returns 409 when Live Cast is off for the project, or when the organization's published projects already meet its allowance. Requires the Org Owner or Org Admin role; 403 when the plan has no Live Cast.
Unpublish Live Cast
Unpublishes the project's Live Cast. Its public page stops serving at once and its seat is freed; verdicts and manual overrides are kept. Requires the Org Owner or Org Admin role; 403 when the plan has no Live Cast.
List project MCP links
Lists the MCP connections a project has linked, so its agent sessions can use them. Requires view access to the project; a linked connection the caller cannot see is left out. Each entry names the connection, its server URL and transport, never its secrets.
Delete project MCP link
Unlinks an MCP connection from a project; the credential stays attached. Requires edit access to the project, plus ownership of the credential or the Org Owner or Org Admin role. Returns 404 when it is not linked there, 204 with no body otherwise.
Get project MCP link
Reads one MCP connection a project has linked. Requires view access to the project. Returns 404 when the connection is not linked there or the caller cannot see it.
Link MCP connection to project
Links an MCP connection to a project, so its agent sessions reach that server, and attaches the credential to the project if it is not attached yet. Requires edit access to the project, plus ownership of the credential or the Org Owner or Org Admin role. A system credential, an agent account's own key or a credential that is not an MCP connection returns 422; otherwise returns 201 when linked and 200 when already linked.
List project members
Lists the users who reach the project through a role on it or its organization, directly or through a group.
Get memory feed status
Returns whether each of the project's memory capture feeds and checks is active, inactive or off, with when each last ran and the last code map commit.
List memory units
Lists the project's memory units, newest first, with their kind, status, trust, provenance and, per unit, how many tasks had it in the prompt (`injected`), were shown it by the hook (`seen`), read or cited it (`used`) and flagged it wrong (`wrong`).
Purge memory unit
Permanently deletes a memory unit and removes it from every stored runner prompt that carried it. Requires permission to edit the project.
Release memory unit
Releases a memory unit the canon check holds, so runners are given it again by its usual rules. Returns 409 for a unit that is not held. Requires permission to edit the project.
Retire memory unit
Retires a memory unit, so no runner is given or shown it again. Requires permission to edit the project.
Get merge lane
Returns the project's merge lane at a glance, read-only: whether it is active (and why not), whether it is still draining after a switch-off, how many entries its queue, history, runs, certificates and flaky tests hold, and when it last swept. It also names the integration branch when the lane found it red (the failing tests and the fix task), a lane run that holds the lane without taking batches (its task id and state: `paused`, `awaiting_response` or `draft`), the nodes its runs are kept off and until when, and PRs whose auto-merge was armed outside the lane.
List merge lane certificates
Returns one page of the merge lane's certificates (a tree the full gate passed and the PRs it merged), newest first, with the total; pages with `limit` (up to 100) and `offset`.
List merge lane flaky tests
Returns one page of the merge lane's flaky tests, newest first, with the total; pages with `limit` (up to 100) and `offset`.
List merge lane history
Returns one page of the merge lane's settled rows (merged, superseded or closed), newest change first, with the total; pages with `limit` (up to 100) and `offset`.
List merge lane quarantined tests
Returns one page of the tests the merge lane's gate runs without gating on, because they flaked in the last 30 days, newest flake first, with the total and each one's `until`; pages with `limit` (up to 100) and `offset`.
List merge lane queue
Returns one page of the merge lane's open rows (queued, testing or failed), newest change first, with each row's PR, state and failing tests and the total; pages with `limit` (up to 100) and `offset`.
List merge lane runs
Returns one page of the merge lane's runs, newest first, with each run's PRs, time running and outcome and the total; pages with `limit` (up to 100) and `offset`.
Stop merge lane
Stops a merge lane that is off but still draining: closes every row on its queue, ends each of its runs that has not ended, paused ones included, and tells each live runner its PR is its own to merge. Refused (409) while the lane is on.
Get outcome scan
Returns the project's outcome scan: when the last scan was filed, the commit and time it read up to, the interval in force and whether it comes from the project, the organization or the default, whether anyone's forge login can run it, and the scan running now, if any. Requires the Org Owner or Org Admin role.
Run outcome scan now
Files the project's outcome scan now, whether or not it is due, and returns the scan's state. Files nothing, and says why, while a scan is running, when nobody's forge login can read the repository, when the project has no repository, or when the organization's plan does not include Agent performance. Requires the Org Owner or Org Admin role.
Get pipeline
Gets a project's pipeline: its stages in order (name, branch, address and where it came from, the level the branch implies, the deploy target, the address's last health check, and the gates that verify a change after it arrives), the step into each stage after the first (what it does, who may do it, approvals needed, whether it runs by itself, and its gates in order with a one-line summary each), each step's approval, timing and concurrency rules, the freezes, Freeze now, and whether a release is running.
Save project pipeline
Replaces a project's pipeline in one save, in the order sent: a stage with an id is updated, one without is added, one left out is removed, with one step per stage after the first; `freezes`, a step's `gates` and a stage's `after` gates and `target`, when sent, replace what is stored, and are kept when left out. A running release finishes on its old settings, and each save that changes something is recorded in the pipeline's history. Requires Edit on the project, and custom mode on a plan with custom pipelines (409 otherwise); a stage out of order, a name or branch used twice, a step or freeze rule out of range (named in `field`), a gate the step cannot take (naming the stage and gate), or a step an org pipeline rule set to Block refuses is refused with 422, and the response's warnings list the rules set to Warn it breaks.
Get project pipeline mode
Gets a project's pipeline mode: one of the two basic pipelines (PR into integration branch, or Integration + Release), custom, or none for a project without a repository; whether its org's plan includes custom pipelines, whether a custom pipeline is read-only because the plan no longer does, each repository's integration branch, the release branch, the address of each live stage, and when the pipeline was last reset to a basic.
Set project pipeline mode
Sets a project's pipeline mode. A basic rewrites the pipeline to that basic's stages in one save (keeping each stage's history where a stage of the same name or role exists), with an optional release branch and live stage addresses; custom keeps the stages and opens the full pipeline editor. Requires Edit on the project; a project without a repository is refused with 422, and custom off the plan with 409.
Bulk pipeline items
Archives, restores or deletes drafts among a project's pipeline items (`task_ids`, or `all_in_stage` with `stage`). Archive hides any task that is not running, drafts included, and never deletes it; restore puts it back where its work says it is; a running task is refused with its reason. Answers how many were done and which were refused and why.
Get pipeline CI workflows
Lists a project's CI workflows on its own forge, read with your own forge connection, for a CI gate's picker: each `{id, name, path}`, where `id` is what the gate stores: a GitHub workflow file, an Azure Pipelines pipeline id, a Bitbucket custom pipeline, or a GitLab job (`*` for the whole pipeline). GitLab and Bitbucket are read from their CI file on the default branch. Empty when the list cannot be read: type the name instead.
Draft pipeline
Shows what a project's pipeline would be if started from a preset or copied from another project of its organization, without saving anything: the save body for the pipeline save, the changes from the saved pipeline, and what that save would refuse. Copying takes stage names, branches and step rules; never addresses or freezes. Requires Edit on the project; a source project the caller cannot view, or in another organization, is a 404.
List pipeline history
Lists a project's pipeline saves, newest first: who saved, when, and what each changed, as sentences. Pages by keyset: pass `next_cursor` back as `cursor` to continue; it is null on the last page.
Restore pipeline
Brings back the stages, steps and freezes as one earlier save left them, as a new save recorded in the history. Requires Edit on the project, and custom mode on a plan with custom pipelines (409 otherwise); an unknown save returns 404.
Get pipeline items
Lists a project's pipeline items in screen order: one stage's (`stage` is its id or `not_started`, `done`, `archived`) or every stage's, each a task as the task list shows it or a merged change no task owns (never a pull request), with its group in the stage, which `group` filters by. Takes the task list's filters and pages by keyset, at most 200 rows a page: pass the `X-Next-Cursor` header back as `after`. A release stage adds its releases, newest first, the newest grouped by feature.
Preview pipeline
Previews a pipeline save without writing it: for the work already on the pipeline, which items would face a different next step (approvals, by hand or by itself, who may do it, a removed stage) and which scheduled releases a changed freeze would hold or release. Requires Edit on the project; a draft the save would refuse returns its 422.
Get pipeline release heads
Gets the project's next release under the list's filters, for the Done list's Next release row, or with `stage` that release stage's, as the Pipeline lists it.
Get pipeline release page
Lists a page of a project's arrived releases, newest first, 50 at a time, each with its task count, tokens and dollars under the list's filters (a release keeping none of the filtered tasks is left out), for the Done list and a release stage's rows. Pass `older_than` back as `before` for the next page; it is null when no older release is left.
Get pipeline releases items
Gets several releases' items grouped by feature in one read, for a release stage drawn as one list.
Get pipeline release items
Gets one release's items grouped by feature, for a release folded in a stage's list.
Act on pipeline step
Acts on the step into a stage: `go` presses it (Start, Move, Merge, or Deploy on a release, which `scheduled_for` schedules), `approve` or `reject` (an approver's, each with an optional `comment`), or `cancel`. A step on tasks takes `subjects` (`task_ids`, `shas`, or `all_in_stage` for every item of the stage before the step, rows never loaded included) and answers how many were done, which were refused and why, and how many wait for approvals; `reject` refuses an item not waiting for approvals as `not_waiting`. A release step acts on its release and answers a refusal with its status (403 for a caller the step does not allow, 409 `not_signed_off` while a sign-off stage before it misses changes, 409 `verifying` while the stage before it still verifies its newest change, 422 `no_source` for a step with no branch stage before it, and 409 `no_release` for `approve`, `reject` or `cancel` with no open release into the stage); `override_reason` on a `go` of a step that merges or deploys runs that one request through a freeze, audited (at least 10 characters, else 422 `reason_short`; a caller who may also edit the project, else 403 `override_forbidden`), and with any other verb answers 422 `override_not_supported`; a `go` on a step whose ticket gate asks when pressed needs `ticket`, a ticket key like `OAM-123` (422 `ticket_required` without one, unless an open release into that stage already carries one; `ticket_invalid` for text that is not a key), a step that asks for none ignores it, and a field the body does not declare returns 422.
Resume pipeline step
Resumes a by-itself release step paused after a release that skipped the normal path; the pause also lifts once the stage before the step has every change its stage has. Recorded in the audit log, it answers 204, or 403 for a caller the step does not allow.
Unlink pipeline template
Unlinks a project from its pipeline template: every value stays and every field becomes editable. Requires Edit on the project, and custom mode on a plan with custom pipelines (409 otherwise).
Link pipeline template
Links a project to a pipeline template: its pipeline becomes the template's published version, as one save. Fields the template locks take its values; open fields keep the project's own on stages it already had. Requires Edit on the project, and custom mode on a plan with custom pipelines (409 otherwise); 409 `template_unpublished`, and 422 when an org pipeline rule set to Block refuses the result (the project is unchanged).
Preview pipeline template link
Shows what linking a project to a pipeline template would change (each change from the saved pipeline) and what would refuse it, without saving anything. Requires Edit on the project; 409 `template_unpublished` when the template was never published.
Get pipeline ticket
Looks up the ticket typed for a step whose ticket gate asks for one when pressed: `{found, key, status, url}`, read with the gate's credential as you may use it. A step that asks for no ticket returns 404; a ticket system that can't be read returns 422 with a sentence saying why.
Get pipeline ticket states
Lists the states a ticket gate can wait for, read from the ticket system with a credential you may use on the project: a Jira project's statuses (or the site's, when neither the credential nor `jira_project` names a project), or ServiceNow's change request states. Each `{id, name}`, where `id` is what the gate stores. A credential you can't use, or a system that can't be read, returns 422 with a sentence saying why.
Get pipeline view
Gets a project's daily pipeline: each stage in order with its count (always present, 0 included), its failures and the version live on it; the version live on Production; each step between two stages with what is in flight, failed or waiting on it, its approvals, its open or failed release, what the caller can do (act, approve, cancel, schedule) and any freeze; and the counts of tasks not started, done without code, and archived. Each count equals the items `GET โฆ/pipeline/items` lists for it.
Get project placement groups
Returns where a project runs: `mode` all (every organization node) or groups, its groups, whether they are in effect on the current plan (`active`), whether you may change them (`editable`), and the nodes its tasks can start on now: `nodes` names those you can see, with each one's status, and `node_count` counts them all.
Set project node groups
Replaces a project's node groups; an empty `group_ids` puts it back on all nodes. Naming groups needs the Node groups plan feature (403 otherwise); a change that takes away a node its tasks are using returns 409 until sent with `confirm`. Requires the Org Owner or Org Admin role.
Get incident automations
Lists the automations that turn a project's incidents into tasks (When: Incident, Release failed or Health breach, targeting that project), each with its kind and status. Org Admins only.
Connect Bitbucket deploys
Creates a project's one record-only Bitbucket Cloud webhook (repo:push, repo:commit_status_created, repo:commit_status_updated) on its first connected Bitbucket repository, recording build statuses on the named production branch (optionally only the named status keys or names) as deploys. Answers the new webhook's ingress URL and secret once; a second call updates the branch and statuses. Org Admins only.
Connect deploys
Adds deploy workflow paths to a project and creates whichever record-only deploy triggers it lacks (on GitHub, none named when its Pages build from the branch). On GitHub it installs the webhooks itself and answers `state` `connected`, or `needs_setup` with `reason` and the GitHub App's `install_url`, never a secret; any other forge answers each new trigger's ingress URL and secret once. Needs Edit on the project.
Connect deploys manually
The manual fallback when Connect deploys could not install the webhooks: on GitHub it tries the install first and, when that works, answers `connected` with no secret; otherwise it answers each deploy trigger's ingress URL and its secret while that secret has not been shown, for pasting into the forge. Needs Edit on the project.
Create default automations
Creates whichever of the four default incident automations a project lacks (Release failed, Monitor incidents, Health breach, Regressions and slowdowns), each filing a task in that project and owned by the caller, and lists the project's incident automations. They file nothing while Production QA is off. Org Admins only.
Get deploy triggers
Returns a project's deploy workflows, which forge its Connect deploys takes, whether the caller may connect it, and the record-only GitHub, GitLab, Azure DevOps or Bitbucket triggers that record its deploys, each with its events, repository and ingress URL; never a secret. Needs Edit on the project.
Get deploy workflows
GitHub: the workflow files on the Production branch that run on a push to it (what Connect deploys prefills), whether the repository publishes GitHub Pages from the branch with no such workflow, and whether the repository could be read at all. Never an error for an unreadable repository. Needs Edit on the project.
Get project release
Gets a project's release tab: its stages in order (Dev first, Production last) with what is on each and the next action the caller may take, the changes waiting on each step, the open releases, the freezes, and whether the caller may deploy. A project without a repository returns an empty tab: no stages and nothing waiting.
Deploy release
Deploys one step: everything waiting on `from_stage_id` moves to the next stage, or only the waiting changes listed in `change_ids`; answers 201 with the new release, or 200 with the step's release already open; a pick of only some waiting changes answers 409 `open` while a release into the stage is open, `state` when a listed change is not waiting, and 422 `no_changes` for an empty list. A freeze covering now answers 409 with `code` `frozen` and `until`, unless `scheduled_for` is later, or `override_reason` or `through_freeze` (no reason typed) runs it through the freeze; the caller must be allowed to deploy to the target stage (else 403), and a step whose ticket gate asks for a ticket when pressed needs `ticket` (else 422 `ticket_required`); a sign-off stage before the target that misses waiting changes answers 409 `not_signed_off` with their `count`, and a source stage still verifying its newest change 409 `verifying` with a `reason`. `untested_reason`, or `untested` with no reason typed, ships the stage's head without waiting for its tests, with the same right as `override_reason` and, for a typed reason, its minimum length (403 `override_forbidden`, 422 `reason_short`), never with `change_ids` (422 `untested_pick`) and never once the step's release is running or approved (409 `open`).
Set freeze now
Switches Freeze now on or off: while on, every stage after the integration stage is frozen until it is switched off. Each switch is recorded in the audit log. Requires Edit on the project.
List release history
Lists a project's releases, newest first. Pages by keyset: pass `next_cursor` back as `cursor` to continue; it is null on the last page.
Survey release
Asks for a fresh count of what each stage's branch holds, so commits merged straight on the forge show as waiting (`extra_commits`). Files one only when none is open and the last is over an hour old, and only for a caller allowed to deploy; answers `filed` true when it filed one.
Approve release
Approves a release waiting for approval, with an optional comment. The last approval needed queues it (or schedules it). Only the step's approvers may (403 `not_approver`); its requester may not while the step blocks self-approval (403 `own_item`).
Cancel release
Cancels a release that has not finished. The requester or anyone allowed to deploy to its target may cancel, else 403. A release already canceled is returned as it is; one that finished answers 409 `state` with its `state`.
Reject release
Rejects a release waiting for approval, with an optional comment: it is canceled and its requester told. Only the step's approvers may (403 `not_approver`).
Retry release
Retries a release that failed before its merge: it is queued again on the same pinned commit and PR, and its failed checks re-run before the merge. Needs the right to deploy to its target (else 403); a release not failed answers 409 `state`, one that failed after its merge or for another reason `not_retryable`, and one a later release into the same stage replaced `superseded`.
Get project runnable nodes
Lists the nodes a task of this project may be pinned to: the enabled nodes it runs on that you can see, by name.
Search project tracker issues
Searches issues by key or title words across every tracker connection the project is linked to, only in its linked tracker projects. Each result names its connection, tracker, key, title and link; a connection that fails is listed under errors with its reason while the others still answer. Requires create access to tasks in the project.
Get project tracker issue
Reads one issue from a linked tracker, with its description. 404 when the issue isn't in a tracker project linked to this project; 502 with the tracker's reason when it can't be read. Requires create access to tasks in the project.
List project trackers
Lists the tracker connections the project is linked to, each with its tracker projects, which link is primary, how many other projects link each, whether the link auto-starts imported tasks, and the connection's last error reaching its tracker. Says whether the caller may edit the links and connect a tracker. Requires view access to the project.
List available trackers
Lists the organization's tracker connections the project may link to: their ids, trackers and names, no credential or setting. Requires edit access to the project.
Delete project tracker
Unlinks the project from a connection. A primary link passes to the tracker project's oldest remaining link; tasks already linked to an issue stay linked. Requires edit access to the project.
Link project tracker
Links the project to a connection's tracker projects, replacing its earlier links to that connection; an empty list keeps the connection linked with none picked. A tracker project's first link is its primary, which receives tracker-started tasks. Requires edit access to the project; another organization's connection returns 404.
Set project tracker auto start
Turns the link's Auto-start imported tasks on or off; new links start off. Off, a task an issue starts in this project waits as a draft until someone starts it, and Jaah tells the issue so. Requires edit access to the project; a connection the project doesn't link returns 404.
List project tracker containers
Lists the connection's teams, projects or spaces as the tracker reports them now; 502 with the tracker's reason when it can't list them. Requires edit access to the project.
Make project tracker primary
Makes the project the primary link of one of its tracker projects, so tracker-started tasks land in it. Requires edit access to the project.