{ "openapi": "3.1.0", "info": { "title": "Entire API", "version": "0.1.0", "description": "Unified Entire API gateway. Aggregates the control plane and regional repository-operation services behind a single endpoint." }, "servers": [ { "url": "https://aws-us-east-2.api.entire.io/api/v1" } ], "paths": { "/git/repos/resolve": { "get": { "operationId": "resolveRepo", "parameters": [ { "description": "Prefixed repository path (et/project/repo, git/owner/repo, or gh/owner/repo); the surface prefix is required. A trailing \".git\" is an optional alias on et/ and gh/ paths.", "explode": false, "in": "query", "name": "repoPath", "required": true, "schema": { "description": "Prefixed repository path (et/project/repo, git/owner/repo, or gh/owner/repo); the surface prefix is required. A trailing \".git\" is an optional alias on et/ and gh/ paths.", "minLength": 1, "type": "string" } }, { "description": "Include hosting-node base URIs.", "explode": false, "in": "query", "name": "includeReplicas", "schema": { "default": false, "description": "Include hosting-node base URIs.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Resolve repository path", "tags": [ "repositories" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/authors": { "post": { "operationId": "listAuthors", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuthorsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuthorsResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "List distinct commit authors", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/branch-membership": { "post": { "operationId": "checkBranchMembership", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMembershipRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/BranchMembership" }, "type": "object" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Classify commits by branch membership", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/branch-protection": { "get": { "description": "Branch protection lives on the repository's data primary and is replicated nowhere. On a read-only native-mirror placement this returns 412 naming the primary's URL, rather than reporting no rules.", "operationId": "getBranchProtection", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "explode": false, "in": "query", "name": "ref", "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchProtectionResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get branch protection", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/branches": { "get": { "operationId": "listBranches", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "explode": false, "in": "query", "name": "search", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "regex", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "pageSize", "schema": { "format": "int32", "maximum": 500, "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBranchesResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "List branches", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "post": { "description": "If the target ref is in the Entire-owned namespace (refs/heads/entire/native/*) and this placement does not own it, the write is forwarded to the owning placement and applied there. Read-your-writes then lags replication by seconds: a read against this placement immediately afterwards may not show the new tip. A forwarded write is an ordinary push at the owner, so a namespace branch marked server-side-merge-only cannot be merged through this placement and must be merged from the owner cell.", "operationId": "createBranch", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchResponse" } } }, "description": "Created", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "push" ] } ], "summary": "Create branch at a commit", "tags": [ "repositories", "git-write" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/branches-containing": { "post": { "operationId": "branchesContaining", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchesContainingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": "object" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "List branches containing each commit", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/branches/{branch...}": { "delete": { "description": "The delete succeeds only while the branch still points at expectedSHA. Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-write/branch-not-found`: the branch is absent on this placement.\n- 412 `https://entire.com/errors/merge-preview/expected-sha-mismatch`: the branch is not at expectedSHA.\n- 403 `https://entire.com/errors/git-write/branch-protected`: branch protection refuses the delete. Protection is checked before the default-branch rule, so a protected default branch also answers this.\n- 409 `https://entire.com/errors/git-write/default-branch`: HEAD points at the branch.\n- 403 with no type: the token does not permit the delete, or the name is in a reserved namespace.\n- 404 with no type: the token cannot read the repository, or this node does not serve the route. It never means that the branch is gone.\n- 400: the branch name is not a valid branch, the ref is symbolic, or expectedSHA is the zero hash or does not match the repository's hash format.\n- 422: a parameter fails validation, such as a missing or malformed expectedSHA.\n- 503: a dependency could not answer, such as the protection check, authorization, or a re-read after a lost race. Retry.\n- Types under `https://entire.com/errors/mirror/` are the mirror problems that every write shares. A read-only placement answers 403 `https://entire.com/errors/mirror/read-only-placement`.\n\nOn a GitHub mirror, GitHub owns the ordinary branches. A ref in the Entire-owned namespace (refs/heads/entire/native/*) belongs to its owning placement. When this placement does not own the ref, the delete goes to the owner. The 404 and 412 answers then reflect this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final. Every refusal at the owner answers 409 `https://entire.com/errors/mirror/upstream-refused`. That includes a branch that is already deleted, that moved, or that is protected at the owner. An unreachable owner answers 502.", "operationId": "deleteBranch", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch to delete, bare (\"feature/x\") or fully qualified (\"refs/heads/feature/x\").", "in": "path", "name": "branch", "required": true, "schema": { "description": "Branch to delete, bare (\"feature/x\") or fully qualified (\"refs/heads/feature/x\").", "maxLength": 1024, "minLength": 1, "type": "string" } }, { "description": "Commit the branch must point at. The delete fails with 412 when the branch has moved.", "explode": false, "in": "query", "name": "expectedSHA", "required": true, "schema": { "description": "Commit the branch must point at. The delete fails with 412 when the branch has moved.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "423": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Locked" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [ "push" ] } ], "summary": "Delete branch", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/commits": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "listCommits", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "explode": false, "in": "query", "name": "ref", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "minLength": 1, "type": "string" } }, { "description": "Exclude commits reachable from this revision; accepts the same ^/~N suffix as ref.", "explode": false, "in": "query", "name": "notRef", "schema": { "description": "Exclude commits reachable from this revision; accepts the same ^/~N suffix as ref.", "type": "string" } }, { "explode": false, "in": "query", "name": "since", "schema": { "format": "date-time", "type": "string" } }, { "explode": false, "in": "query", "name": "until", "schema": { "format": "date-time", "type": "string" } }, { "explode": false, "in": "query", "name": "path", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "author", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "firstParent", "schema": { "default": false, "type": "boolean" } }, { "explode": false, "in": "query", "name": "parseTrailers", "schema": { "default": false, "type": "boolean" } }, { "description": "Include diff stats (additions, deletions, filesChanged) per commit. Stats that exceed the per-commit timeout are omitted (null).", "explode": false, "in": "query", "name": "includeStats", "schema": { "default": false, "description": "Include diff stats (additions, deletions, filesChanged) per commit. Stats that exceed the per-commit timeout are omitted (null).", "type": "boolean" } }, { "explode": false, "in": "query", "name": "pageSize", "schema": { "format": "int32", "maximum": 200, "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommitsResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "List commits", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/commits/batch": { "post": { "operationId": "batchCommits", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCommitsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/Commit" }, "type": "object" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get commits by SHA in batch", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/commits/last-changed": { "post": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "lastChangedCommits", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LastChangedCommitsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LastChangedCommitsResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get the last commit that changed each path", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/compare": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "compareCommits", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. \u003csha\u003e^ for a commit's first parent).", "explode": false, "in": "query", "name": "base", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. \u003csha\u003e^ for a commit's first parent).", "minLength": 1, "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2).", "explode": false, "in": "query", "name": "head", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2).", "minLength": 1, "type": "string" } }, { "explode": false, "in": "query", "name": "path", "schema": { "type": "string" } }, { "description": "Include per-file additions, deletions, and binary detection. Set false to return paths and change status only.", "explode": false, "in": "query", "name": "includeStats", "schema": { "default": true, "description": "Include per-file additions, deletions, and binary detection. Set false to return paths and change status only.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Compare commits", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/compare/status": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "compareStatus", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "explode": false, "in": "query", "name": "base", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "explode": false, "in": "query", "name": "head", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareStatusResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Compare branch status", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/diff": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "getDiff", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. \u003csha\u003e^ for a commit's first parent).", "explode": false, "in": "query", "name": "base", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. \u003csha\u003e^ for a commit's first parent).", "minLength": 1, "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2).", "explode": false, "in": "query", "name": "head", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2).", "minLength": 1, "type": "string" } }, { "explode": false, "in": "query", "name": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get unified diff", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/files": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "getFiles", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "explode": false, "in": "query", "name": "ref", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "minLength": 1, "type": "string" } }, { "explode": true, "in": "query", "name": "path", "required": true, "schema": { "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get files", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/merge-base": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.", "operationId": "getMergeBase", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix.", "explode": false, "in": "query", "name": "commitA", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix.", "minLength": 1, "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix.", "explode": false, "in": "query", "name": "commitB", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeBaseResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get merge base", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/merge-previews": { "post": { "operationId": "previewMerge", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunMergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunMergeResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Preview merge", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/merges": { "post": { "description": "If the target ref is in the Entire-owned namespace (refs/heads/entire/native/*) and this placement does not own it, the write is forwarded to the owning placement and applied there. Read-your-writes then lags replication by seconds: a read against this placement immediately afterwards may not show the new tip. A forwarded write is an ordinary push at the owner, so a namespace branch marked server-side-merge-only cannot be merged through this placement and must be merged from the owner cell.", "operationId": "createMerge", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [ "push" ] } ], "summary": "Merge branch", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/objects/batch": { "post": { "operationId": "batchObjects", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchObjectsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get blobs by object id in batch", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/raw": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.\n\nWhen the ref resolves but the file is absent, the answer is a 404 with the Entire-Path and Entire-Size headers set and no problem body.", "operationId": "getFileByQuery", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "explode": false, "in": "query", "name": "ref", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "minLength": 1, "type": "string" } }, { "explode": false, "in": "query", "name": "path", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get raw file", "tags": [ "repositories", "git-read" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/raw/{path...}": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.\n\nWhen the ref resolves but the file is absent, the answer is a 404 with the Entire-Path and Entire-Size headers set and no problem body.", "operationId": "getFile", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "explode": false, "in": "query", "name": "ref", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "minLength": 1, "type": "string" } }, { "in": "path", "name": "path", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get raw file by path", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/rebase-previews": { "post": { "operationId": "previewRebase", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunRebaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunRebaseResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Preview rebase", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/rebases": { "post": { "description": "If the target ref is in the Entire-owned namespace (refs/heads/entire/native/*) and this placement does not own it, the write is forwarded to the owning placement and applied there. Read-your-writes then lags replication by seconds: a read against this placement immediately afterwards may not show the new tip. A forwarded write is an ordinary push at the owner, so a namespace branch marked server-side-merge-only cannot be merged through this placement and must be merged from the owner cell.", "operationId": "createRebase", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebaseRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "push" ] } ], "summary": "Rebase branch", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/refs": { "get": { "operationId": "listRefs", "parameters": [ { "description": "Repository ULID.", "in": "path", "name": "repoId", "required": true, "schema": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Ref-name prefixes to filter by (repeatable), e.g. \"refs/heads/\", \"refs/tags/\", \"HEAD\". Empty returns all visible refs.", "explode": true, "in": "query", "name": "prefix", "schema": { "description": "Ref-name prefixes to filter by (repeatable), e.g. \"refs/heads/\", \"refs/tags/\", \"HEAD\". Empty returns all visible refs.", "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Include the symref target for symbolic refs.", "explode": false, "in": "query", "name": "symrefs", "schema": { "default": false, "description": "Include the symref target for symbolic refs.", "type": "boolean" } }, { "description": "Include the peeled commit for annotated tags.", "explode": false, "in": "query", "name": "peel", "schema": { "default": false, "description": "Include the peeled commit for annotated tags.", "type": "boolean" } }, { "description": "Emit an unborn HEAD (a symbolic HEAD whose branch has no commits yet).", "explode": false, "in": "query", "name": "unborn", "schema": { "default": false, "description": "Emit an unborn HEAD (a symbolic HEAD whose branch has no commits yet).", "type": "boolean" } }, { "description": "Max refs to return (default 100, max 500).", "explode": false, "in": "query", "name": "pageSize", "schema": { "description": "Max refs to return (default 100, max 500).", "format": "int32", "maximum": 500, "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRefsResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "List references", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/revert-previews": { "post": { "operationId": "previewRevert", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunRevertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRunRevertResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Preview revert", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/reverts": { "post": { "description": "If the target ref is in the Entire-owned namespace (refs/heads/entire/native/*) and this placement does not own it, the write is forwarded to the owning placement and applied there. Read-your-writes then lags replication by seconds: a read against this placement immediately afterwards may not show the new tip. A forwarded write is an ordinary push at the owner, so a namespace branch marked server-side-merge-only cannot be merged through this placement and must be merged from the owner cell.", "operationId": "createRevert", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [ "push" ] } ], "summary": "Revert commit", "tags": [ "repositories", "git-write" ] }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/tags": { "get": { "operationId": "listTags", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "explode": false, "in": "query", "name": "search", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "regex", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "pageSize", "schema": { "format": "int32", "maximum": 500, "minimum": 0, "type": "integer" } }, { "explode": false, "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagsResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "List tags", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/git/repos/{repoId}/tree": { "get": { "description": "Read the problem type, not only the status.\n\n- 404 `https://entire.com/errors/git-read/ref-not-found`: a requested ref does not resolve on this placement. A new repository answers this until its first push.\n- 404 `https://entire.com/errors/git-read/object-missing`: an object is absent on this placement. Retry.\n- 404 `https://entire.com/errors/git-read/repo-gone`: the repository has no refs and the object is absent.\n- 404 with no type: the token cannot read the repository, or the cause is none of the above.\n\nOn a GitHub mirror or a ref forwarded to its owner, a 404 reflects this placement's view, which can lag the owner. A caller that acts on a mirror must not treat that 404 as final.\n\nA 404 `https://entire.com/errors/git-read/path-not-found` means the ref resolves, but the path is absent or names a file.", "operationId": "getTree", "parameters": [ { "in": "path", "name": "repoId", "required": true, "schema": { "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "explode": false, "in": "query", "name": "ref", "required": true, "schema": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^).", "minLength": 1, "type": "string" } }, { "explode": false, "in": "query", "name": "path", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "recursive", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTreeResponse" } } }, "description": "OK", "headers": { "X-Entire-Replicas": { "schema": { "description": "Comma-separated base URIs of the nodes currently hosting this repository.", "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Not Found" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [ "pull" ] } ], "summary": "Get tree", "tags": [ "repositories", "git-read" ], "x-entire-published": true }, "x-upstream": "entiredb" }, "/search/api/search": { "get": { "operationId": "searchCode", "summary": "Full-text code search", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }, { "name": "org_id", "in": "query", "schema": { "type": "string" }, "description": "Organization ID filter" }, { "name": "repo", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Repository ID(s) to search in" }, { "name": "max_results", "in": "query", "schema": { "type": "integer", "default": 1000 }, "description": "Maximum results to return" }, { "name": "case_sensitive", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Enable case-sensitive matching (default is case-insensitive)" } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too many concurrent queries" }, "504": { "description": "Query timeout exceeded" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/fuzzy": { "get": { "operationId": "fuzzySearch", "summary": "Fuzzy file path or symbol search", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }, { "name": "org_id", "in": "query", "schema": { "type": "string" } }, { "name": "repo", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "max_results", "in": "query", "schema": { "type": "integer", "default": 1000 } }, { "name": "symbols", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Search symbols instead of file paths" }, { "name": "kind", "in": "query", "schema": { "type": "string" }, "description": "Filter by symbol kind (only with symbols=true)" }, { "name": "defs", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Only definitions (only with symbols=true)" } ], "responses": { "200": { "description": "Fuzzy search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuzzyResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too many concurrent queries" }, "504": { "description": "Query timeout exceeded" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/repos": { "get": { "operationId": "listRepos", "summary": "List indexed repositories", "parameters": [ { "name": "org_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of repositories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReposResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/repos/{repo_id}": { "get": { "operationId": "getRepo", "summary": "Get repository details", "parameters": [ { "name": "repo_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Repository details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoEntry" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Repository not found" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/file": { "get": { "operationId": "getFileContent", "summary": "Get file content from a repository", "parameters": [ { "name": "repo", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Repository ID" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "File path within the repository" }, { "name": "symbols", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include symbols (definitions, references) in the response" } ], "responses": { "200": { "description": "File content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Repository or file not found" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/symbols": { "get": { "operationId": "getSymbols", "summary": "Extract symbols from a file", "parameters": [ { "name": "repo", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Symbols in the file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolsResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Repository or file not found" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/usages": { "get": { "operationId": "getUsages", "summary": "Find cross-file usages of a definition", "parameters": [ { "name": "repo", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Repository ID" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "File path containing the definition" }, { "name": "line", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Line number of the definition" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Selects among several definitions on the line (`import { a, type B } from ...`). Without it the line's first definition in index order is used.\n" }, { "name": "max", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "Maximum usages to return" } ], "responses": { "200": { "description": "Usages of the definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsagesResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "File or definition not found" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/hover": { "get": { "operationId": "getHover", "summary": "LSP-style hover info for a definition", "description": "Full declaration header (return type, generics, receiver) and the leading doc comment for the definition at a line, computed by re-parsing the file at query time.\n", "parameters": [ { "name": "repo", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Repository ID" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "File path containing the definition" }, { "name": "line", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Line number of the definition" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Disambiguates lines holding several definitions. Without it, a multi-definition line yields 404 rather than an arbitrary symbol.\n" } ], "responses": { "200": { "description": "Hover info for the definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoverResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "File or definition not found, or language unsupported" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/blame": { "get": { "operationId": "getBlame", "summary": "Blame attribution for a file, from the index's attribution section", "description": "Pure mmap read, no git. Returns an empty `runs` array whenever there's no provenance to show — attribution wasn't enabled at build time, the file has no runs, or the requested range has no overlap.", "parameters": [ { "name": "repo", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Repository ID" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "File path to blame" }, { "name": "start", "in": "query", "schema": { "type": "integer" }, "description": "Optional 1-based start line (0 is rejected with 400); filters to runs overlapping [start, end]. Filtering only activates when both `start` and `end` are given — `start` alone is a no-op and every run is returned." }, { "name": "end", "in": "query", "schema": { "type": "integer" }, "description": "Optional 1-based end line (0 is rejected with 400); filters to runs overlapping [start, end]. Filtering only activates when both `start` and `end` are given — `end` alone is a no-op and every run is returned." }, { "name": "max", "in": "query", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 10000 }, "description": "Maximum runs returned (clamped to 10000). When more overlapping runs exist, the response sets truncated=true." } ], "responses": { "200": { "description": "Blame runs for the file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlameResponse" } } } }, "400": { "description": "start greater than end, or a 0 line bound" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "File not found" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/search/api/resolve": { "post": { "operationId": "resolveReferences", "summary": "Resolve symbol references to definitions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } } }, "responses": { "200": { "description": "Resolved references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResult" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Repository or file not found" } }, "security": [ { "bearerAuth": [] } ], "tags": [ "search" ] }, "x-upstream": "peregrine" }, "/insights/projects/{project_id}/trail-metrics": { "get": { "operationId": "getTrailMetrics", "tags": [ "insights" ], "summary": "Metrics per merged trail", "description": "One item per merged trail of the project that has a TCO record,\nnewest merge first: ordered by merged_at descending, then repo_id,\ntrail number and installation. Pages hold per_page items (default 50,\nmaximum 200); next_cursor is present only when another page exists.\n\nA parameter given twice, or a bracketed name other than repo_id[eq],\nis invalid_request. Other parameters this document does not list are\nignored. The cursor does not carry per_page, so send it with each page.\nA project_id that is not a ULID gets the same 403 as a project the\ncaller cannot view. Methods other than GET answer 405\nmethod_not_allowed.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo given in repo_id.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "query", "description": "Only this repo's trails, by its public ID (repo_\u003cULID\u003e, as each item's repo_id). Same as repo_id[eq]; must not be empty. If both are given they must be equal. A caller admitted by repo access sends it with every page.", "schema": { "type": "string", "minLength": 1 } }, { "name": "repo_id[eq]", "in": "query", "description": "Only this repo's trails, by its public ID (repo_\u003cULID\u003e); must not be empty.", "schema": { "type": "string", "minLength": 1 } }, { "name": "since", "in": "query", "description": "Only trails merged at or after this RFC 3339 timestamp. Percent-encode a + in an offset (%2B), or use Z.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Only trails merged before this RFC 3339 timestamp. Percent-encode a + in an offset (%2B), or use Z.", "schema": { "type": "string", "format": "date-time" } }, { "name": "has_agent_data", "in": "query", "description": "Only trails whose latest TCO version has at least one model record or phase record, including records with zero tokens. Omitted or false leaves results unchanged. Repeat has_agent_data=true with each page of a filtered list; omitting or changing it with a filtered cursor is invalid_cursor. Filtering applies before pagination.", "schema": { "type": "boolean", "default": false } }, { "name": "has_activity", "in": "query", "description": "Only trails with agent data (at least one model record or phase record on the latest TCO version, including records with zero tokens) or runner spend (at least one runner run, so runners[] is non-empty; a trail whose runners are recorded but none ran does not qualify). Omitted or false leaves results unchanged. Repeat has_activity=true with each page of a filtered list; omitting or changing it with a filtered cursor is invalid_cursor. Combined with has_agent_data=true both apply, so only trails with agent data are returned. Filtering applies before pagination.", "schema": { "type": "boolean", "default": false } }, { "name": "cursor", "in": "query", "description": "A next_cursor from a previous page of the same project. It carries repo_id, since, until, has_agent_data and has_activity; repeating repo_id, since or until is allowed only with the same values. has_agent_data and has_activity must each match the cursor's value (repeat true on each filtered page; omitted means false). An empty value is invalid_cursor; omit it for the first page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Items per page.", "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50 } } ], "responses": { "200": { "description": "A page of trails.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailMetricsPage" } } } }, "400": { "description": "A parameter is invalid (invalid_request) or the cursor does not decode or disagrees with the request (invalid_cursor).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the repo it filters on in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active Agent Insights installation in the project covers the requested repo (or, without repo_id, the project has none). type is https://entire.com/errors/insights/plugin-not-installed and code is insights/plugin-not-installed; clients match type exactly. An empty trail_metrics list instead means installed with no merged trails in the window.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, or the request ran past its 4s deadline (service_unavailable).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/insights/projects/{project_id}/trail-activity-summary": { "get": { "operationId": "getTrailActivitySummary", "tags": [ "insights" ], "summary": "Phase, development and review token totals for merged trails", "description": "Sums all five token counters per raw phase across the project's latest\nstored TCO rows from active installations. trails_with_phases counts\ndistinct Trails with at least one phase row, including zero-token rows.\nPhase names are sorted; grouping for display stays with the client.\nUses the same merged_at window and repo scope as trail-metrics: since\nis inclusive and until is exclusive. Omitted bounds are unbounded. No\npagination is needed.\n\ndevelopment.tokens is the sum of all five counters over every phase\nrow in scope, review_fix included, equal to the sum of phases[] tokens;\nit never counts runner tokens. review.tokens is the\nsum of the four runner counters (fresh_input, output, cache_write,\ncache_read) over every runner run of Trails in scope, as trail-metrics\nshows in runners; all runners count and none is identified. A Trail\nwith no runner runs adds 0, and no has_activity filter applies. A repo\ncovered by two active installations is counted once per installation,\nas in trail-metrics and the phase totals.\n\nInstalled scopes with no rows return trails_with_phases 0, phases [],\nand development and review tokens of 0. Responses permit future\nadditive fields; clients should ignore unknown properties and accept\nnew phase names. Responses from servers that predate these totals may\nomit development and review; read a missing one as not available,\nnever as 0.\nA parameter given twice, or a bracketed name other than repo_id[eq],\nis invalid_request. Other undocumented parameters are ignored.\nA project_id that is not a ULID gets the same 403 as a project the\ncaller cannot view. HEAD is also accepted by the GET route. Methods\nother than GET and HEAD answer 405 method_not_allowed.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo given in repo_id.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "query", "description": "Only this repo's trails, by its public ID (repo_\u003cULID\u003e, as trail-metrics' repo_id). Same as repo_id[eq]; must not be empty. If both are given they must be equal. A caller admitted by repo access must send it.", "schema": { "type": "string", "minLength": 1 } }, { "name": "repo_id[eq]", "in": "query", "description": "Only this repo's trails, by its public ID (repo_\u003cULID\u003e); must not be empty.", "schema": { "type": "string", "minLength": 1 } }, { "name": "since", "in": "query", "description": "Only trails merged at or after this RFC 3339 timestamp. Percent-encode a + in an offset (%2B), or use Z.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Only trails merged before this RFC 3339 timestamp. Percent-encode a + in an offset (%2B), or use Z.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Phase totals with their distinct Trail count, and development and review token totals.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailActivitySummary" } } } }, "400": { "description": "A parameter is invalid (invalid_request).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the repo it filters on in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active Agent Insights installation in the project covers the requested repo (or, without repo_id, the project has none). type is https://entire.com/errors/insights/plugin-not-installed and code is insights/plugin-not-installed; clients match type exactly. Zero trails_with_phases and an empty phases array instead mean installed with no phase rows in the window.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, or the request ran past its 4s deadline (service_unavailable).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/insights/projects/{project_id}/repos/{repo_id}/trails/{number}/metrics": { "get": { "operationId": "getSingleTrailMetrics", "tags": [ "insights" ], "summary": "Metrics for one merged or open trail", "description": "Returns one TrailMetrics object directly, not a page, using the same\ncomputed data as trail-metrics, including phase tokens when available.\nOnly the path's project, repo and trail number are considered; query\nparameters are ignored; callers cannot supply a branch.\n\nStored merged metrics return provisional false, unchanged. When no\nstored record exists, entire-api supplies the Trail state and branch.\nOpen Trails return provisional true with merged_at null, computed from\ningested checkpoints at one request-time UTC cutoff. Merged Trails not\nyet computed return provisional true with merged_at set to the Trail's\nmerge time, computed at that merged_at cutoff, the same cutoff the\nstored metrics will use. Provisional Trails with no matching checkpoints\nreturn 200 with empty models and phases arrays.\nProvisional totals are not persisted and may change as work is ingested.\nSuccessful provisional responses always include runners and runner_usage.\nRunner reads use the active core installation and authoritative repo/Trail ID,\nenumerate all review/monitor waves, and include reported usage in every status.\nRuns created at or before runner_usage.run_created_at_lte are eligible:\nrequest-start UTC for open Trails, merged_at for provisional merged Trails.\nThis inclusive creation bound is NOT a frozen usage snapshot; counters are\nobserved as pages are fetched and may increase during enumeration.\nReads are limited to 100 pages, 10,000 raw run records (including duplicates)\nand 10 seconds, respecting client cancellation. Failed usage reads,\nmalformed run identity/time, repeated pagination tokens and exceeded budgets\nanswer sanitized 503 service_unavailable, never partial-success zero.\n\nClosed-unmerged, unknown or unreadable Trails (including upstream 403),\nand merged Trails with no merged_at, answer 404 insights/not-found.\nA transient Trail lookup failure or unconfigured lookup answers sanitized\n503 service_unavailable, without upstream details. This is distinct from the 404\ninsights/plugin-not-installed for a repo with no active installation.\nA project_id that is not a ULID gets the same 403 as a project the\ncaller cannot view. Methods other than GET answer 405\nmethod_not_allowed.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo in the path.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "path", "required": true, "description": "The repo's public ID, repo_\u003cULID\u003e, as trail-metrics' repo_id.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "The positive trail number in this repo.", "schema": { "type": "integer", "minimum": 1, "format": "int64" } } ], "responses": { "200": { "description": "One merged or open trail's metrics. Open Trails have provisional true, merged_at null and models and phases arrays, including when empty. Merged Trails not yet computed have provisional true, merged_at set and the same arrays.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailMetrics" } } } }, "400": { "description": "The trail number is malformed, out of int64 range or nonpositive (invalid_request).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the path's repo in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active installation of the project covers the repo: code is\ninsights/plugin-not-installed and type is\nhttps://entire.com/errors/insights/plugin-not-installed.\nInstalled but closed-unmerged, unknown, unreadable (including upstream 403),\nor merged with no merged_at: code is insights/not-found and type is\nhttps://entire.com/errors/insights/not-found. All use the same response,\nwithout upstream details. Clients match type exactly or branch on code.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, a transient Trail lookup failed or was unconfigured, or the request ran past its 4s deadline (service_unavailable). Details are sanitized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/insights/projects/{project_id}/repos/{repo_id}/trails/{number}/breakdown": { "get": { "operationId": "getTrailBreakdown", "tags": [ "insights" ], "summary": "Token use of one merged or open trail, as a tree of nodes", "description": "Returns one TrailBreakdown object. In v1 every top-level node has kind\nsession and basis exact. New kinds may appear: clients render a node of\nan unknown kind by its totals under a generic label and never drop it.\nbasis is exact or estimated. children is empty in v1; where a later\nversion fills it, children sum to their parent for every token field,\nbut not for calls.\n\nWhen computed from the same ingested data, the top-level nodes sum\nexactly to the same Trail's metrics totals, for calls and for every\ntoken field. A Claude Code call repeated by resumed or forked sessions\ncounts once, under one session, the lowest session ID, so a resumed\nsession can look cheaper than it was. A session whose calls are all\ncounted under another session has no node, so there can be fewer nodes\nthan the metrics sessions count.\n\nA merged Trail's breakdown is computed from its stored checkpoint set,\nread at the record's own extractor version. A checkpoint of one of its\nsessions landing later, on any branch, can change the split before the\nrequeued computation stores new totals: until then the response is\nprovisional true with merged_at set, and its sums can differ from the\nstored metrics. An open Trail is provisional true with merged_at null,\ncomputed from ingested checkpoints at one request-time UTC cutoff, and\nmay change as work is ingested.\n\nAuthorization and method handling are the same as for the single-trail\nmetrics operation. Unlike it, a merged Trail with no stored record\nanswers 404 insights/not-found, as do closed-unmerged, unknown or\nunreadable Trails; a repo with no active installation answers 404\ninsights/plugin-not-installed.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo in the path.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "path", "required": true, "description": "The repo's public ID, repo_\u003cULID\u003e, as trail-metrics' repo_id.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "The positive trail number in this repo.", "schema": { "type": "integer", "minimum": 1, "format": "int64" } } ], "responses": { "200": { "description": "The trail's breakdown. Open Trails have provisional true and merged_at null; a merged Trail awaiting recomputation after a late checkpoint has provisional true and merged_at set. nodes is empty when the Trail has no agent work.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailBreakdown" } } } }, "400": { "description": "The trail number is malformed, out of int64 range or nonpositive (invalid_request).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the path's repo in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active installation of the project covers the repo: code is\ninsights/plugin-not-installed and type is\nhttps://entire.com/errors/insights/plugin-not-installed.\nInstalled but closed-unmerged, unknown, unreadable (including upstream 403),\nor merged and not yet computed: code is insights/not-found and type is\nhttps://entire.com/errors/insights/not-found. All use the same response,\nwithout upstream details. Clients match type exactly or branch on code.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, a transient Trail lookup failed or was unconfigured, or the request ran past its 4s deadline (service_unavailable). Details are sanitized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/insights/projects/{project_id}/repos/{repo_id}/trails/{number}/turns": { "get": { "operationId": "getTrailTurns", "tags": [ "insights" ], "summary": "The most expensive turns of one trail for a set of phases", "description": "Returns one TrailTurns object: the limit most expensive turns among\nthe trail's calls that have a share in any of the given phases,\nordered by tokens descending, then by call time, session ID and call\nID; and totals for the whole phase set, so a client can show how many\nturns and tokens are not listed. A turn is one model call, identified\nby session_id and call_id; turn_index is the ordinal of the human\nprompt it followed (0 before the first).\n\nThe calls are the same ones the trail's metrics count: a merged\nTrail's stored checkpoint set, read at the record's own extractor\nversion, or an open Trail's live branch at one request-time UTC\ncutoff, provisional true with merged_at null, which may change as work\nis ingested. A checkpoint of one of a merged Trail's sessions landing\nlater, on any branch, can change which calls count before the\nrequeued computation stores new totals: until then the response is\nprovisional true with merged_at set, and its totals can differ from\nthe stored metrics. A call split across phases counts only\nits share: each token count is the call's multiplied by the summed\nweight of its phases in the set. totals.tokens is the sum of the\nset's per-phase totals as the metrics operation rounds them, so for\nthe same ingested data it equals the sum of the same Trail's phases\nentries for those phases. Each listed turn is rounded on its own, so\nthe listed turns can differ from the totals by a few tokens when\ncalls are split across phases. The phase set is raw phase names;\ngrouping phases into activities is the client's. A phase no call has\nmatches nothing; a set that matches no call answers 200 with empty\nturns and zero totals.\n\nphase is required and may be repeated; limit may be given once. A\nbracketed name is invalid_request; other unlisted parameters are\nignored. Authorization, method handling and the 404 cases are the\nsame as for the trail breakdown operation.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo in the path.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "path", "required": true, "description": "The repo's public ID, repo_\u003cULID\u003e, as trail-metrics' repo_id.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "The positive trail number in this repo.", "schema": { "type": "integer", "minimum": 1, "format": "int64" } }, { "name": "phase", "in": "query", "required": true, "description": "A raw phase name, as a trail's phases[].phase. Repeat the parameter for a set; duplicates are ignored. Must not be empty.", "schema": { "type": "string", "minLength": 1 }, "explode": true }, { "name": "limit", "in": "query", "description": "How many turns to list, highest tokens first (default 10, maximum 200). The totals cover the whole set regardless. This is a ranked top-N, not a page of a collection, so there is no cursor and the parameter is limit rather than per_page; a client that wants more turns raises limit.", "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 10 } } ], "responses": { "200": { "description": "The trail's most expensive turns in the phase set and the set's totals. Open Trails have provisional true and merged_at null; a merged Trail awaiting recomputation after a late checkpoint has provisional true and merged_at set.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailTurns" } } } }, "400": { "description": "The trail number is malformed, out of int64 range or nonpositive; phase is missing or empty; limit is not an integer from 1 to 200 or is repeated; or a parameter is bracketed (invalid_request).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the path's repo in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active installation of the project covers the repo: code is\ninsights/plugin-not-installed and type is\nhttps://entire.com/errors/insights/plugin-not-installed.\nInstalled but closed-unmerged, unknown, unreadable (including upstream 403),\nor merged and not yet computed: code is insights/not-found and type is\nhttps://entire.com/errors/insights/not-found. All use the same response,\nwithout upstream details. Clients match type exactly or branch on code.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, a transient Trail lookup failed or was unconfigured, or the request ran past its 4s deadline (service_unavailable). Details are sanitized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/insights/projects/{project_id}/repos/{repo_id}/status": { "get": { "operationId": "getRepoStatus", "tags": [ "insights" ], "summary": "Processing status of one repo", "description": "Whether an active Agent Insights installation of the project covers the\nrepo, and how current its trail metrics are. For a caller with view\naccess to the project, a repo no installation covers is a 200 with\ninstalled false and state not_installed, not a 404.\nunprocessed_trails and failed_trails count only merged trails intake has\nalready found; a trail merged since intake last read the repo is in\nneither. A project_id that is not a ULID gets the same 403 as a project\nthe caller cannot view. Methods other than GET answer 405\nmethod_not_allowed. Other parameters this document does not list are\nignored.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo in the path.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "path", "required": true, "description": "The repo's public ID, repo_\u003cULID\u003e, as trail-metrics' repo_id. A caller with view access to the project gets 200 with state not_installed for an ID no installation covers; a caller admitted by repo access alone gets 403.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The repo's status.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoStatus" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the repo in the path in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, or the request ran past its 4s deadline (service_unavailable).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/insights/projects/{project_id}/repos/{repo_id}/trail-stats": { "get": { "operationId": "getTrailStats", "tags": [ "insights" ], "summary": "Token use of a repo's merged trails of one size", "description": "Peers are the repo's merged trails, each at its latest TCO version,\nwith a current change size in the bucket, merged at or after since,\nminus trail. During a regeneration peers can mix TCO versions. A\ntrail with no model rows is a peer with 0 tokens. without_cache_reads\nleaves out cache reads; cache writes stay in. Statistics are null,\nnever omitted, when they cannot be computed. A parameter other than\nphase given twice, or a bracketed name, is invalid_request; other\nunlisted parameters are ignored. A project_id that is not a ULID gets\nthe same 403 as a project the caller cannot view. Methods other than\nGET answer 405 method_not_allowed.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "The project's ID (a ULID). The caller needs view access to it, or reader, writer or admin access to the repo in the path.", "schema": { "type": "string" } }, { "name": "repo_id", "in": "path", "required": true, "description": "The repo's public ID, repo_\u003cULID\u003e, as trail-metrics' repo_id.", "schema": { "type": "string" } }, { "name": "bucket", "in": "query", "required": true, "description": "The size bucket of the peers, as a trail's size.bucket; one of S, M, L, XL.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": true, "description": "Only peers merged at or after this RFC 3339 timestamp. Percent-encode a + in an offset (%2B), or use Z.", "schema": { "type": "string", "format": "date-time" } }, { "name": "trail", "in": "query", "description": "A trail number in this repo to leave out of the peers and place among them (trail_percentile).", "schema": { "type": "integer", "minimum": 1, "format": "int64" } }, { "name": "phase", "in": "query", "description": "A raw phase name, as a trail-metrics phases[].phase (for example review_fix); repeat it for a set of phases, up to 32. Given, each cache variant also carries phase_share_median, phase_share_p90 and trail_phase_share for the set. Duplicates are ignored, and a phase no trail has (such as an unknown name) has a share of 0, not an error. Grouping phases into activities is the caller's.\n", "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 32, "items": { "type": "string", "minLength": 1 } } } ], "responses": { "200": { "description": "The peers' statistics.", "headers": { "X-Agent-Insights-Version": { "$ref": "#/components/headers/AgentInsightsVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailStats" } } } }, "400": { "description": "bucket or since is missing or invalid, trail is not a positive int64, a phase is empty or given more than 32 times, or another parameter is repeated or bracketed (invalid_request).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The bearer token is not valid (unauthenticated). A request with no Authorization header is refused by the gateway before it reaches this service, and that body has no code.", "headers": { "WWW-Authenticate": { "description": "Always Bearer.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The caller is not an account, or has neither view access to the project nor reader, writer or admin access to the path's repo in this project (forbidden). The answer is the same whether or not the project or repo exists or is installed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No active Agent Insights installation in the project covers the repo (insights/plugin-not-installed); type is https://entire.com/errors/insights/plugin-not-installed. An installed repo with no peers is a 200 with trails 0.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected failure (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The token or the caller's access could not be checked, or the request ran past its 4s deadline (service_unavailable).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-upstream": "agent-insights" }, "/semantic-search/search/v1/search": { "get": { "operationId": "search", "summary": "Hybrid search across indexed entities", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 500 }, "description": "Search query (max 500 characters)" }, { "name": "types", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated entity types to search. Any of: repos, checkpoints, commits, prs, sessions. Defaults to all types when omitted." }, { "name": "repo", "in": "query", "schema": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 250 } }, "style": "form", "explode": true, "description": "Restrict results to specific repositories by repo ULID (case-insensitive; normalized to canonical uppercase). Repeatable; duplicate values are ignored. Omitted = all accessible repos. Full names (values containing '/'), blank values, more than 100 values, or values over 250 characters are rejected with 400. A filter matching none of the caller's accessible repos is rejected with 404." }, { "name": "branch", "in": "query", "schema": { "type": "string", "maxLength": 250 }, "description": "Restrict results to a branch (max 250 characters)" }, { "name": "author", "in": "query", "schema": { "type": "string" }, "description": "Restrict results to an author" }, { "name": "date", "in": "query", "schema": { "type": "string", "enum": [ "week", "month" ] }, "description": "Restrict results to the last week or month" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "hybrid", "keyword" ] }, "description": "Search mode. Defaults to hybrid." }, { "name": "filter_type", "in": "query", "schema": { "type": "string", "enum": [ "checkpoints", "commits", "sessions" ] }, "description": "Narrow a single-type search further (legacy CLI/compat path, ENT-1363). When set, the response is one type with the global limit cut and page honored. When omitted, per-type caps apply instead (see limit/page)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 500 }, "description": "Maximum results to return (1-500, default 20). Without filter_type this is a per-type cap (ENT-1363): up to limit results of each type are returned in one response, and a type that hit its cap is flagged in truncated_types. With filter_type it is the page size." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number. Only honored with filter_type; ignored on the per-type-capped path (ENT-1363)." } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/entire-search__SearchResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The caller's core JWT verified but carries no account id in its subject; search requires a subject that identifies the account. (Legacy ent_* API tokens and GitHub tokens are rejected with 401 — a core JWT is the only accepted credential.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "An explicit repo filter matched none of the caller's accessible repos (typo'd, unknown, or inaccessible — existence is not disclosed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "Raw query string exceeds the 32 KiB limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shed by admission control: the process-wide in-flight search budget stayed full past the acquire wait, or the caller already holds its per-account share. Carries `Retry-After` (seconds); retry after it with bounded backoff. Nothing was searched.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Search failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Repository access could not be fully resolved (repo enumeration was capped) while an explicit repo filter went unmatched — the filter may live in the unenumerated remainder, so the miss is retryable rather than a definitive 404 (ENT-1114).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The per-search deadline elapsed before a phase that cannot return partial results (repo resolution, query embedding) completed. A deadline that lands mid-fan-out returns a partial 200 instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ "semantic-search" ] }, "x-upstream": "entire-search" }, "/semantic-search/search/v1/health": { "get": { "operationId": "health", "summary": "Liveness/readiness probe", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } }, "tags": [ "semantic-search" ] }, "x-upstream": "entire-search" }, "/ci/plugins/{plugin}/deliveries": { "get": { "description": "Recent event deliveries to the plugin's webhook URL, newest first. Requires an account access token that holds project#manage on the plugin's owner project. Each cell holds the deliveries it sent, so this lists this cell's deliveries only.", "operationId": "listPluginDeliveries", "parameters": [ { "description": "Plugin slug", "in": "path", "name": "plugin", "required": true, "schema": { "description": "Plugin slug", "type": "string" } }, { "description": "Optional: restrict to this installation", "explode": false, "in": "query", "name": "installation_id", "schema": { "description": "Optional: restrict to this installation", "type": "string" } }, { "description": "Deliveries per page", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 30, "description": "Deliveries per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous page's next_cursor", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a previous page's next_cursor", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPluginDeliveriesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "List a plugin's webhook deliveries", "tags": [ "plugin-deliveries" ] }, "x-upstream": "ci-webhooks" }, "/ci/plugins/{plugin}/deliveries/{id}": { "get": { "description": "The stored request and every recorded attempt with its response. Requires an account access token that holds project#manage on the plugin's owner project. Each cell holds the deliveries it sent, so this lists this cell's deliveries only.", "operationId": "getPluginDelivery", "parameters": [ { "description": "Plugin slug", "in": "path", "name": "plugin", "required": true, "schema": { "description": "Plugin slug", "type": "string" } }, { "description": "Delivery id", "in": "path", "name": "id", "required": true, "schema": { "description": "Delivery id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDeliveryDetailView" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a plugin webhook delivery and its attempts", "tags": [ "plugin-deliveries" ] }, "x-upstream": "ci-webhooks" }, "/ci/repos/{id}/branch-checks": { "get": { "description": "Every check the branch requires, with the newest build on the branch at any commit that ran to an answer (passed, failed, or blocked at a block step, which reads as success; canceled, skipped and not_run builds are passed over), normalized to GitHub check-run semantics. Takes the caller's own account access token, authorized against repo#pull or repo#manage_ci, or a repo-bound ops token.", "operationId": "getBranchChecks", "parameters": [ { "description": "Bare repository group ULID; entire-api workload only", "explode": false, "in": "query", "name": "repo_group_id", "schema": { "description": "Bare repository group ULID; entire-api workload only", "type": "string" } }, { "description": "Repository ULID", "in": "path", "name": "id", "required": true, "schema": { "description": "Repository ULID", "type": "string" } }, { "description": "Branch name, or a refs/heads/... ref", "explode": false, "in": "query", "name": "branch", "schema": { "description": "Branch name, or a refs/heads/... ref", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchChecksSnapshot" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Not Implemented" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Newest finished CI build per required check on a branch", "tags": [ "checks" ] }, "x-upstream": "ci-webhooks" }, "/ci/repos/{id}/checks": { "get": { "description": "Every check the branch requires, with the newest attempt at the commit, normalized to GitHub check-run semantics. Takes the caller's own account access token, authorized against repo#pull or repo#manage_ci, or a repo-bound ops token.", "operationId": "getChecks", "parameters": [ { "description": "Bare repository group ULID; entire-api workload only", "explode": false, "in": "query", "name": "repo_group_id", "schema": { "description": "Bare repository group ULID; entire-api workload only", "type": "string" } }, { "description": "Repository ULID", "in": "path", "name": "id", "required": true, "schema": { "description": "Repository ULID", "type": "string" } }, { "description": "Commit SHA the checks report on", "explode": false, "in": "query", "name": "commit", "schema": { "description": "Commit SHA the checks report on", "type": "string" } }, { "description": "Branch name, or a refs/heads/... ref", "explode": false, "in": "query", "name": "branch", "schema": { "description": "Branch name, or a refs/heads/... ref", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecksSnapshot" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Internal Server Error" }, "501": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Not Implemented" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ci-webhooks__ErrorModel" } } }, "description": "Service Unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Normalized CI checks for a commit on a branch", "tags": [ "checks" ] }, "x-upstream": "ci-webhooks" }, "/brain/v1/health": { "get": { "operationId": "health__brainstore", "summary": "Liveness check", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "timestamp": { "type": "string" } } } } } } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/facts": { "post": { "operationId": "upsertFacts", "summary": "Idempotently upsert a batch of fact records", "description": "The collection's only POST is the batch upsert. The body is NDJSON of entire-brain factmerge records (the module's wire contract, snake_case), identity-verified per record; one invalid record rejects the whole batch. New fact ids insert rows with server-stamped attribution from the token. Existing ids union provenance anchors and advance status one way (active to superseded or retracted, superseded to retracted); regressions are ignored, so re-uploads are idempotent and never churn the feed. Facts whose anchors match an already-merged trail are stamped with its trail id.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "One factmerge record per line; at most 5000 records and 32 MiB per request." } } } }, "responses": { "200": { "description": "Per-record outcome counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" }, "changed": { "type": "integer" }, "unchanged": { "type": "integer" } } } } } }, "400": { "description": "Invalid repo id, malformed or forged record, invalid status, empty body, or more than 5000 records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInRegion" }, "413": { "description": "Request body exceeds 32 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "get": { "operationId": "listFactChanges", "summary": "Repo-wide fact change feed", "description": "Pages all of a repo's facts in server-change order (updated_at ASC, fact_id ASC). No pageToken replays from the beginning; clients filter locally (e.g. by git reachability of anchor commits). A status change or trail stamp bumps a fact's position, so retractions and merges re-deliver through the feed. Unlike a finite list, any non-empty page carries a resume nextPageToken; only an empty (caught-up) page returns null.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "A page of fact changes", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "record": { "$ref": "#/components/schemas/FactRecord" }, "trailId": { "type": "string", "description": "Merged trail this fact belongs to; empty until its trail merges." }, "createdBy": { "type": "string" }, "createdByHandle": { "type": "string", "description": "Server-stamped display handle; attribution only, never an authz input." }, "updatedAt": { "type": "string", "description": "Server change stamp (ISO 8601, milliseconds)." } } } }, "nextPageToken": { "type": "string", "nullable": true, "description": "Resume cursor; null only when the page is empty (caught up)." } } } } } }, "400": { "description": "Invalid repo id or pageToken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInRegion" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/trails/{trailId}/merged": { "post": { "operationId": "recordTrailMerge", "summary": "Record a trail merge and stamp its facts", "description": "Core notifies brainstore that a trail merged, carrying the trail's membership. Membership unions; facts whose anchors match any member are stamped with the trail id. Idempotent against redelivery (a repeat stamps 0). Facts uploaded later with matching anchors are stamped at upsert.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" }, { "name": "trailId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one member across the three lists; at most 5000 total.", "properties": { "sessions": { "type": "array", "items": { "type": "string" } }, "checkpoints": { "type": "array", "items": { "type": "string" } }, "commits": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Membership recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "stamped": { "type": "integer", "format": "int64", "description": "Facts newly stamped with this trail id." } } } } } }, "400": { "description": "Invalid repo id, invalid trail id, empty membership, or more than 5000 members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInRegion" }, "413": { "description": "Request body exceeds 32 MiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/memories": { "get": { "operationId": "listMemories", "summary": "List the memories read model", "description": "FTS-filtered, recency-ordered (updated_at DESC, fact_id ASC) fact rows with provenance anchors, so a UI can render where each memory came from. Repo-wide by default; branch filters on display metadata only (branch is never a storage key).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 }, "description": "Optional display-branch filter. maxLength is 512 BYTES, not characters." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full-text search query, parsed via websearch_to_tsquery (web search syntax; never raises on malformed input)." }, { "name": "trail", "in": "query", "required": false, "description": "Comma-separated or repeated Trail IDs. Use no-trail for unlinked memories. Applied before pagination.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Comma-separated or repeated values, OR within this field and AND across fields. Applied before pagination.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Comma-separated or repeated values, OR within this field and AND across fields. Applied before pagination.", "schema": { "type": "string" } }, { "name": "author", "in": "query", "required": false, "description": "Comma-separated or repeated values, OR within this field and AND across fields. Applied before pagination.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageToken" } ], "responses": { "200": { "description": "A page of memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryItem" } }, "nextPageToken": { "type": "string", "nullable": true, "description": "Set when the page was full; null on the last page." } } } } } }, "400": { "description": "Invalid repo id, branch, or pageToken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInRegion" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/memories/facet-candidates": { "get": { "operationId": "listMemoryFacetCandidates", "summary": "List repository memory filter candidates", "description": "Distinct authors and Trail IDs with compact visibility evidence across all repository facts, independent of search, filters and list pagination. The caller must apply default-branch reachability to unlinked anchored candidates before exposing them as repository browser choices. No fact text is returned. More than 10000 candidates returns 503, never a partial list.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" } ], "responses": { "200": { "description": "Complete repository filter candidates", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "author", "trailId", "commit", "unanchored" ], "properties": { "author": { "type": "string" }, "trailId": { "type": "string" }, "commit": { "type": "string" }, "unanchored": { "type": "boolean" } } } } } } } } }, "400": { "description": "Invalid repository ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInRegion" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/memories/queries": { "post": { "operationId": "queryMemories", "summary": "List the memories read model, filtered by anchor or trail membership", "description": "The anchor/trail-filtered counterpart to GET /memories, for callers that need multi-value filtering GET's single q/branch params can't express (e.g. a trail's full session/checkpoint/commit join) — the filter lists carry up to 5000 values, beyond what query params hold, so this is a POST query sub-resource rather than GET params. sessionIds, checkpointIds, commits, and trailIds are ORed together (a memory matches if any anchor value or its trailId matches any listed value); empty strings are stripped before matching. Pages the same (updated_at DESC, fact_id ASC) keyset as GET /memories, so a nextPageToken from either endpoint is valid input to the other.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one value across the four lists after stripping empty strings; at most 5000 total.", "properties": { "sessionIds": { "type": "array", "items": { "type": "string" } }, "checkpointIds": { "type": "array", "items": { "type": "string" } }, "commits": { "type": "array", "items": { "type": "string" } }, "trailIds": { "type": "array", "items": { "type": "string" } }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Out-of-range values are clamped (below 1 to 50, above 100 to 100), never rejected." }, "pageToken": { "type": "string", "description": "Opaque cursor from a prior nextPageToken. An unparseable or stale token is a 400 (restart without a token), never a silent first page." } } } } } }, "responses": { "200": { "description": "A page of memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryItem" } }, "nextPageToken": { "type": "string", "nullable": true, "description": "Set when the page was full; null on the last page." } } } } } }, "400": { "description": "Invalid repo id, empty filter, more than 5000 values, or invalid pageToken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotInRegion" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/memories/{fact_id}": { "patch": { "operationId": "editMemory", "summary": "Replace a memory's statement with a successor fact", "description": "Mints a successor fact for the new text (content-derived id, same paths), copies the original's anchors, kind, and trail stamp, and advances the original to superseded pointing at the successor — the original row and its provenance are preserved, never rewritten. An edit whose normalized text matches an existing ACTIVE fact links to that fact instead of inserting a duplicate; matching a superseded or retracted fact is a 409 (the one-way status lattice cannot reactivate it). Normalized text that leaves the id unchanged is a no-op. Requires repo write access.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" }, { "$ref": "#/components/parameters/FactID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 16384, "description": "Replacement statement; must normalize non-empty. maxLength is BYTES." } } } } } }, "responses": { "200": { "description": "The successor memory (the original, when the edit was a no-op)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryItem" } } } }, "400": { "description": "Invalid repo id, fact id, body, or text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/MemoryNotFound" }, "409": { "$ref": "#/components/responses/MemoryConflict" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "delete": { "operationId": "retractMemory", "summary": "Retract a memory", "description": "Advances the fact to retracted (from active or superseded) — the one-way terminal state behind the memories drawer's Delete and the trail review's Deny. Idempotent. The row is never deleted: history and lineage stay readable. Requires repo write access.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" }, { "$ref": "#/components/parameters/FactID" } ], "responses": { "200": { "description": "The retracted memory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryItem" } } } }, "400": { "description": "Invalid repo id or fact id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/MemoryNotFound" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/repos/{repo_id}/brain/memories/{fact_id}/accept": { "post": { "operationId": "acceptMemory", "summary": "Accept a memory in review", "description": "Records that the caller reviewed and kept an active fact (trail review's Accept). Acceptance is a fact attribute, not a lifecycle status: the fact stays active, nothing reaches the sync feed, and the read model reports accepted=true from then on. Idempotent. Requires repo write access.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RepoID" }, { "$ref": "#/components/parameters/FactID" } ], "responses": { "200": { "description": "The accepted memory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryItem" } } } }, "400": { "description": "Invalid repo id or fact id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/MemoryNotFound" }, "409": { "$ref": "#/components/responses/MemoryConflict" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "tags": [ "brainstore" ] }, "x-upstream": "brainstore" }, "/agents/models": { "get": { "description": "Lists the models a project agent may set for each harness, with the harness's default model and reasoning effort. A create or replace whose model is not an accepted id for its harness returns 422; hidden models are accepted but not listed. Requires a signed-in caller.", "operationId": "agentModelsList", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentModels" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List agent models", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/agents/presets": { "get": { "description": "Lists Entire's agent presets as they are now: version, name, instructions, signal, harness, model and timeout. Run one in a project with POST /{host}/{project}/agents and its preset id; the agent follows the preset as it changes. Requires a signed-in caller.", "operationId": "agentPresetsList", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageAgentPreset" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List agent presets", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/agents/presets/{id}": { "get": { "description": "Returns one preset as it is now. Requires a signed-in caller.", "operationId": "agentPresetGet", "parameters": [ { "description": "Preset id.", "in": "path", "name": "id", "required": true, "schema": { "description": "Preset id.", "maxLength": 64, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPreset" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get an agent preset", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/cache/prs": { "get": { "description": "Your open pull requests across every repository you belong to, most-recently-updated first.", "operationId": "cacheOpenPRs", "parameters": [ { "description": "Extra computed fields to include; supported: activity", "explode": true, "in": "query", "name": "include", "schema": { "description": "Extra computed fields to include; supported: activity", "items": { "enum": [ "activity" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PRsListOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your open pull requests across your repositories", "tags": [ "pull-requests" ] }, "x-upstream": "activity" }, "/editor-documents/{documentKey}/content": { "put": { "description": "Replaces an editor document's content wholesale, for callers holding a complete document rather than a Yjs update to merge (automation, CLI, MCP): the yjs-engine sidecar computes an in-lineage replacement from the document's current state, which is then written through the same guarded, bounded-retry loop as the merge route. Unlike a merge, a wholesale replace cannot reconcile with a concurrent write, so two orthogonal controls guard it: If-Match for concurrency, and onlyIfEmpty for \"write only if there is nothing to lose\" — the latter is not concurrency control and declines with a no-op rather than an error. Both are re-evaluated on every retry, so a write landing mid-flight cannot slip past a check that already passed. Rejected input and content the engine cannot apply are 422; an unreachable engine or exhausted retries are 503. Service-only, same sync_editor_documents gate as the sibling sync routes.", "operationId": "editorContentPut", "parameters": [ { "description": "Editor document key.", "in": "path", "name": "documentKey", "required": true, "schema": { "description": "Editor document key.", "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write of this document, as returned by the sync GET or this route. If present, the request 412s when it no longer matches the document's current ETag. Omit to apply unconditionally.", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write of this document, as returned by the sync GET or this route. If present, the request 412s when it no longer matches the document's current ETag. Omit to apply unconditionally.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditorContentPutBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditorContentPutResponseJSON" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Replace an editor document's content wholesale (service)", "tags": [ "trails-internal" ] }, "x-upstream": "activity" }, "/editor-documents/{documentKey}/sync": { "get": { "description": "Rehydrates the trail-body editor: the document's current yjsState (the CRDT source of truth once present) and its contentJson projection. Service-only — the caller must hold the sync_editor_documents platform grant; end-user authorization happened upstream at the websocket route.", "operationId": "editorSyncGet", "parameters": [ { "description": "Editor document key.", "in": "path", "name": "documentKey", "required": true, "schema": { "description": "Editor document key.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditorSyncDocumentJSON" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Read editor document sync state (service)", "tags": [ "trails-internal" ] }, "x-upstream": "activity" }, "/editor-documents/{documentKey}/updates": { "post": { "description": "Merges a Yjs update into an editor document via the yjs-engine sidecar (ENT-1231): reads the current state, calls the engine, then writes the merged state and its contentJson projection conditional on the row it read being unchanged. On a conflict (another merge landed first, or the key was recreated under a new row) it re-reads and re-merges — safe because CRDT merge is commutative and idempotent — up to a bounded number of attempts, after which it 503s rather than retrying forever. 503 also covers an unreachable, slow, or misbehaving engine; 422 covers non-retryable input — a malformed account id, or an update the engine cannot apply or that exceeds its body cap. Service-only, same sync_editor_documents gate as the sibling sync routes.", "operationId": "editorUpdatePost", "parameters": [ { "description": "Editor document key.", "in": "path", "name": "documentKey", "required": true, "schema": { "description": "Editor document key.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditorUpdatePostBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditorSyncDocumentJSON" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Merge a Yjs update into an editor document (service)", "tags": [ "trails-internal" ] }, "x-upstream": "activity" }, "/experimental/me": { "get": { "description": "Your identity plus the jurisdictions where this service actually holds data for you — the residency footprint of your account.", "operationId": "experimentalGetMe", "parameters": [ { "description": "RFC3339 lower bound for the jurisdiction list; defaults to the last 90 days", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC3339 lower bound for the jurisdiction list; defaults to the last 90 days", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your identity and the jurisdictions where you have data", "tags": [ "experimental" ] }, "x-upstream": "activity" }, "/experimental/me/activity": { "get": { "description": "A residency-aware preview of your activity dashboard. A mirrored repository's placements across regions collapse to a single entry, and the streak is state-agnostic — a worked day counts even if that work is later orphaned.", "operationId": "experimentalGetMyActivity", "parameters": [ { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Restrict to specific repo IDs", "explode": true, "in": "query", "name": "repo_ids", "schema": { "description": "Restrict to specific repo IDs", "items": { "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your aggregated activity dashboard, with per-repository rollups and streaks", "tags": [ "experimental" ] }, "x-upstream": "activity" }, "/experimental/me/checkpoints": { "get": { "description": "A residency-aware preview of your checkpoints, plus streak dates. The streak dates span the last 365 days independent of the list window and are state-agnostic, so a day you worked still counts even if that work was later orphaned.", "operationId": "experimentalListMyCheckpoints", "parameters": [ { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your recent checkpoints, with streak dates", "tags": [ "experimental" ] }, "x-upstream": "activity" }, "/experimental/me/commits": { "get": { "description": "A residency-aware preview of your commits: portable pointers you hydrate from each commit's home region, rather than full content. Orphaned commits are excluded.", "operationId": "experimentalListMyCommits", "parameters": [ { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your recent commits, each with its checkpoints", "tags": [ "experimental" ] }, "x-upstream": "activity" }, "/experimental/me/recap": { "get": { "description": "A residency-aware preview of your per-agent recap. Scoping to a single repository adds a team column covering all of its contributors; if that repository's data lives in another region the team column is omitted and the response tells you to re-request in that region.", "operationId": "experimentalGetMyRecap", "parameters": [ { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Restrict to one repo_id; adds the team column (federated if foreign)", "explode": false, "in": "query", "name": "repo", "schema": { "description": "Restrict to one repo_id; adds the team column (federated if foreign)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecapOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your per-agent activity recap", "tags": [ "experimental" ] }, "x-upstream": "activity" }, "/me/activity": { "get": { "description": "Your activity dashboard for the streak and contribution heatmaps. Days and streaks are bucketed in the timezone you pass; streaks span the last 365 days regardless of the selected timeframe and are state-agnostic, so a later-orphaned day still counts.", "operationId": "getMyActivity", "parameters": [ { "description": "IANA timezone identifier (e.g. Europe/Berlin). Required.", "explode": false, "in": "query", "name": "timezone", "schema": { "description": "IANA timezone identifier (e.g. Europe/Berlin). Required.", "type": "string" } }, { "description": "Window to aggregate", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Window to aggregate", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "Deprecated and ignored: the aggregates cover the whole timeframe", "explode": false, "in": "query", "name": "limit", "schema": { "deprecated": true, "description": "Deprecated and ignored: the aggregates cover the whole timeframe", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeActivityOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your aggregated activity dashboard, with per-repository rollups and streaks", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/checkpoints": { "get": { "description": "Your recent checkpoints, each hydrated with its linking commit, prompt, and sessions. hasCheckpoints covers the last 365 days independent of the list window, and is state-agnostic so a later-orphaned checkpoint still counts.", "operationId": "listMyCheckpoints", "parameters": [ { "description": "Window to return", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Window to return", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "Max rows to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "description": "Max rows to return", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeCheckpointsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your recent checkpoints", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/commits": { "get": { "description": "Your recent commits, each grouped with the checkpoints linked to it. The author shown is each commit's own git author, not you as the viewer.", "operationId": "listMyCommits", "parameters": [ { "description": "Window to return", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Window to return", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "Max rows to return", "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "description": "Max rows to return", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeCommitsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your recent commits, each with its checkpoints", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/dispatch-setups": { "get": { "description": "Your dispatch setups (saved repo/window/voice configurations), each with up to three of its most recent accessible dispatches. A setup's config is masked to the repos you can currently see, and a setup whose repos are all gone is dropped from the list entirely.", "operationId": "listDispatchSetups", "parameters": [ { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Opaque cursor from a prior nextPageToken", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchSetupListOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your dispatch setups, most recently created first", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/dispatch-setups/{setupId}": { "delete": { "description": "Soft-deletes a dispatch setup. Its past runs are left as they are — only new dispatches through it stop being possible.", "operationId": "deleteDispatchSetup", "parameters": [ { "in": "path", "name": "setupId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a dispatch setup", "tags": [ "me" ] }, "get": { "description": "A single dispatch setup, with its single most recent accessible dispatch and its config masked to the repos you can currently see. Reports not found once every one of its repos is gone.", "operationId": "getDispatchSetup", "parameters": [ { "in": "path", "name": "setupId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchSetupWire" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A single dispatch setup, with its most recent dispatch", "tags": [ "me" ] }, "patch": { "description": "Renames and/or pins a dispatch setup. Both fields are independently optional; name additionally accepts null to clear a custom name back to the generated default. Refuses (not found) once every one of the setup's repos is gone — the fields never change on a setup you can no longer see.", "operationId": "updateDispatchSetup", "parameters": [ { "in": "path", "name": "setupId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchSetupPatchInputBody" } }, "application/octet-stream": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchSetupWire" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Rename, pin, or unpin a dispatch setup", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/dispatch-setups/{setupId}/dispatches": { "get": { "description": "A dispatch setup's past runs, most recently created first, filtered to the ones whose own covered repos you can still see.", "operationId": "listDispatchSetupRuns", "parameters": [ { "in": "path", "name": "setupId", "required": true, "schema": { "type": "string" } }, { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Opaque cursor from a prior nextPageToken", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchRunListOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Dispatch runs for one setup, most recently created first", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/dispatches": { "post": { "description": "Starts generating a dispatch: collects checkpoints from the selected repos' home cell, persists a setup + run, then hands the LLM call to a detached background task and returns immediately. 202 with Location pointing at the run's own read route; the response body is the same dispatch shape the read routes serve, with status generating and no markdown yet — poll getDispatch for the result. Rate-limited to one generation per account per minute. A selected repo with no local placement, or one the caller can't currently see, 404s naming it; org scopes are not yet supported.", "operationId": "dispatchGenerate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchGenerateInputBody" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchDetailWire" } } }, "description": "Accepted", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Start generating a dispatch", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/dispatches/{dispatchId}": { "delete": { "description": "Soft-deletes a dispatch run. Deleting it again returns not found, not a repeat 204 — same as one that was never yours or whose covered repos you've since lost access to.", "operationId": "deleteDispatch", "parameters": [ { "in": "path", "name": "dispatchId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a dispatch run", "tags": [ "me" ] }, "get": { "description": "A single dispatch run's full generated markdown and metadata. A run still generating reports status generating; one stuck past the stale threshold reports failed rather than polling forever. A run whose covered repos are no longer (fully) accessible reports not found.", "operationId": "getDispatch", "parameters": [ { "in": "path", "name": "dispatchId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchDetailWire" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A single dispatch run", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/project-trails": { "get": { "description": "Project Trails you authored or that are assigned to you and may read through project authority or a repository in their stored scope, most recently updated first by default. Discovery, authorship, and assignment alone never grant access. An assignment matches your account ID, or your linked GitHub login for legacy assignments; each Trail appears once. Takes the same filters as a project's Trail list (status, phase, type, priority, author, assignee, their _not exclusions, and search), which only narrow your Trails, plus project_id and sort, with cursor/per_page pagination. A cursor is bound to your account and to the filters and sort that produced it. If Core cannot resolve your GitHub login, authored and account-assigned Trails are still listed and meta.partial carries unresolved_caller_login. If the stored Change readiness read fails, building Trails return `changes: []` and meta.partial carries change_readiness_unavailable; a project catalog failure returns 503. Repository Trails are listed by GET /me/trails.", "operationId": "listMyProjectTrails", "parameters": [ { "description": "Match these accessible project ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "project_id", "schema": { "description": "Match these accessible project ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these statuses (repeatable or comma-separated)", "explode": true, "in": "query", "name": "status", "schema": { "description": "Match any of these statuses (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses (repeatable or comma-separated)", "explode": true, "in": "query", "name": "status_not", "schema": { "description": "Exclude these statuses (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these derived phases (repeatable or comma-separated)", "explode": true, "in": "query", "name": "phase", "schema": { "description": "Match any of these derived phases (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these derived phases (repeatable or comma-separated)", "explode": true, "in": "query", "name": "phase_not", "schema": { "description": "Exclude these derived phases (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these priorities (repeatable or comma-separated)", "explode": true, "in": "query", "name": "priority", "schema": { "description": "Match any of these priorities (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these priorities (repeatable or comma-separated)", "explode": true, "in": "query", "name": "priority_not", "schema": { "description": "Exclude these priorities (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these types (repeatable or comma-separated)", "explode": true, "in": "query", "name": "type", "schema": { "description": "Match any of these types (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these types (repeatable or comma-separated)", "explode": true, "in": "query", "name": "type_not", "schema": { "description": "Exclude these types (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Narrow your Trails to these author account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "author", "schema": { "description": "Narrow your Trails to these author account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these author account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "author_not", "schema": { "description": "Exclude these author account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Narrow your Trails to these assignee account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "assignee", "schema": { "description": "Narrow your Trails to these assignee account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these assignee account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "assignee_not", "schema": { "description": "Exclude these assignee account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Case-insensitive search over Trail title, #number, and project identity", "explode": false, "in": "query", "name": "search", "schema": { "description": "Case-insensitive search over Trail title, #number, and project identity", "type": "string" } }, { "explode": false, "in": "query", "name": "sort", "schema": { "default": "updated", "enum": [ "updated", "title", "status", "type", "priority", "assignee" ], "type": "string" } }, { "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor; repeat the same filters and sort", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor; repeat the same filters and sort", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeProjectTrailsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your authored or assigned project Trails", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/recap": { "get": { "description": "Your per-agent recap. Scoping to a single repository adds a team column covering all of that repository's contributors.", "operationId": "getMyRecap", "parameters": [ { "description": "Window to aggregate", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Window to aggregate", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "Restrict to one repo_id; enables the contributors side", "explode": false, "in": "query", "name": "repo", "schema": { "description": "Restrict to one repo_id; enables the contributors side", "type": "string" } }, { "description": "Optional max checkpoints (omit for uncapped)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Optional max checkpoints (omit for uncapped)", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "ISO-8601 lower bound; with until, overrides timeframe", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO-8601 lower bound; with until, overrides timeframe", "type": "string" } }, { "description": "ISO-8601 upper bound; with since, overrides timeframe", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO-8601 upper bound; with since, overrides timeframe", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeRecapOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your per-agent activity recap", "tags": [ "me" ] }, "x-upstream": "activity" }, "/me/sessions": { "get": { "description": "Your sessions from every repository, gathered from your checkpoint activity and merged into one list ordered globally across repositories. Each row carries its repository's route provider (github/entire); a repository with no resolvable provider is dropped and reported via meta.partial rather than linked to a guessed surface. This list has no cursor: it returns up to `limit` rows inside the timeframe and no `next_cursor`; narrow the timeframe or raise `limit` to see more. `kind[ne]` excludes sessions of the given kinds before the limit is applied, so a page is not displaced by rows the caller would hide; sessions with no kind are always included.", "operationId": "listMySessions", "parameters": [ { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Exclude sessions of these kinds, for example agent_review; repeatable or comma-separated.", "explode": true, "in": "query", "name": "kind[ne]", "schema": { "description": "Exclude sessions of these kinds, for example agent_review; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeSessionsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your sessions across all repositories", "tags": [ "me" ], "x-entire-published": true }, "x-upstream": "activity" }, "/me/trails": { "get": { "description": "Trails you authored or that are assigned to you across every repository you belong to, newest first. A trail that you authored and that is assigned to you appears once. The timeframe bounds when a trail was last updated, not when it was opened, and repositories with trails turned off are left out. This list has no cursor: it returns up to `limit` rows inside the timeframe and no `next_cursor`; narrow the timeframe or raise `limit` to see more.", "operationId": "listMyTrails", "parameters": [ { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeTrailsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your trails across all repositories", "tags": [ "me" ], "x-entire-published": true }, "x-upstream": "activity" }, "/preferences/diff-view": { "get": { "operationId": "getDiffView", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffViewResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your diff-view settings", "tags": [ "preferences" ] }, "put": { "operationId": "setDiffView", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffViewPreference" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiffViewResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update your diff-view settings", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/dismissals": { "get": { "description": "Notices you have dismissed, oldest first, so a client can keep them hidden across browsers and devices. A key names the notice and may carry a scope after a colon, such as a repository ID.", "operationId": "getDismissals", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissalPreferences" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your dismissed notices", "tags": [ "preferences" ] }, "post": { "description": "Records that you dismissed a notice. Dismissing it again is a no-op and keeps the original time. The list is capped; once full, the oldest dismissal is dropped and that notice may be shown again.", "operationId": "dismissNotice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissalPreferences" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Dismiss a notice", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/filter-tabs": { "get": { "operationId": "getFilterTabs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTabsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your saved list-filter tabs", "tags": [ "preferences" ] }, "put": { "operationId": "setFilterTabs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTabsPutBody" } }, "application/octet-stream": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTabsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a saved list-filter tab", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/projects": { "get": { "description": "Your favorite project IDs, in the order you added them. A favorite is only a pointer: it carries no project metadata and grants no access, so intersect the list with the projects you can independently see.", "operationId": "getProjectPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPreferences" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your favorite projects", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/projects/favorites": { "post": { "description": "Adds a project to your favorites. Favoriting a project you already favorite is a no-op; the list is capped, and a full list returns a conflict.", "operationId": "favoriteProject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteProjectInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPreferences" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Favorite a project", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/projects/favorites/{project_id}": { "delete": { "description": "Removes a project from your favorites. Removing a project that is not favorited is a no-op.", "operationId": "unfavoriteProject", "parameters": [ { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Unfavorite a project", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/projects/migrate": { "post": { "description": "Imports your browser-local project favorites into your account. It migrates once — only while you have never saved favorites server-side, an empty saved list included — so it never restores a favorite you removed on another device.", "operationId": "migrateProjectPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrateProjectPreferencesInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPreferences" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Import browser-local project favorites once", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/repos": { "get": { "description": "Your pinned and recent repositories. The lists and their order are yours, but each entry's name and runner/trail flags reflect the repository's current shared settings.", "operationId": "getRepoPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your pinned and recent repositories", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/repos/migrate": { "post": { "description": "Imports your browser-local pinned and recent repositories into your account. It migrates once per list — each is imported only while you have no saved entries of that type — so it never overwrites preferences you already keep server-side.", "operationId": "migrateRepoPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesMigrateInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Import your locally-stored repository preferences", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/repos/pinned": { "post": { "operationId": "pinRepo", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoIDBodyInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Pin a repository", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/repos/pinned/{repo_id}": { "delete": { "operationId": "unpinRepo", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Unpin a repository", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/repos/recent": { "post": { "operationId": "addRecentRepo", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentBodyInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Add a repository to your recent list", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/repos/recent/{repo_id}": { "delete": { "operationId": "removeRecentRepo", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPreferencesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Remove a repository from your recent list", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/preferences/session-detail-filters": { "get": { "operationId": "getSessionDetailFilters", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetailFiltersResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Your session-detail filter defaults", "tags": [ "preferences" ] }, "put": { "operationId": "setSessionDetailFilters", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetailPreference" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetailFiltersResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update your session-detail filter defaults", "tags": [ "preferences" ] }, "x-upstream": "activity" }, "/repos/batch": { "post": { "description": "Hydrates an explicit repository-id set from this cell. Repositories that are unknown here or that you cannot view metadata for are silently omitted.", "operationId": "batchRepos", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReposBatchInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReposListOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Hydrate repositories by id", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}": { "get": { "operationId": "repoMeta", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoListItem" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Metadata for one repository", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/activity": { "get": { "description": "Time-bucketed activity counts for one repository, for its activity chart.", "operationId": "repoActivity", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "granularity", "schema": { "default": "day", "enum": [ "day", "week" ], "type": "string" } }, { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityBucketsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Time-bucketed activity for a repository", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/agents": { "get": { "description": "Summarizes every active agent of the repository's project that selects it, by name: what it is called and runs, whether and how it is triggered, and its latest run and reading in this repository. It holds nothing of an agent's configuration beyond that — not the other repositories it selects, nor its environment or instructions: GET /{host}/{project}/agents/{id} returns them to agent managers. Requires pull on the repository.", "operationId": "repoAgentsList", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryAgentsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a repository's agents", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/attachments/{attachmentId}": { "get": { "description": "Redirects to a short-lived presigned URL for a ready attachment when the caller has only its repository and attachment id. Public repositories allow anonymous reads; private repositories require normal repository access. The original bytes are returned without resizing.", "operationId": "repoAttachmentServe", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Attachment id (ULID)", "in": "path", "name": "attachmentId", "required": true, "schema": { "description": "Attachment id (ULID)", "type": "string" } } ], "responses": { "302": { "description": "Found", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Serve a ready trail attachment without a trail number", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/branches": { "get": { "operationId": "repoBranches", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Branches in a repository", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/checkpoint-status": { "get": { "description": "A lightweight availability check for a repository's checkpoints, used to decide whether to show the overview. When the checkpoints are stored separately and aren't available to you, the count is redacted rather than the request failing.", "operationId": "repoCheckpointStatus", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointStatusOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Repository-level checkpoint availability and sync status", "tags": [ "checkpoints" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/checkpoints": { "get": { "operationId": "repoCheckpoints", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Branch to filter to; empty = the repo's default branch", "explode": false, "in": "query", "name": "branch", "schema": { "description": "Branch to filter to; empty = the repo's default branch", "type": "string" } }, { "description": "Optional branch whose reachable commits are excluded: lists only checkpoints on commits reachable from branch but not from this one (git branch ^excludeBranch)", "explode": false, "in": "query", "name": "excludeBranch", "schema": { "description": "Optional branch whose reachable commits are excluded: lists only checkpoints on commits reachable from branch but not from this one (git branch ^excludeBranch)", "type": "string" } }, { "description": "Page size, clamped to 1..1000", "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "description": "Page size, clamped to 1..1000", "format": "int64", "type": "integer" } }, { "description": "RFC 3339 lower bound on the checkpoint's anchoring commit date, inclusive (optional; unbounded by default)", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339 lower bound on the checkpoint's anchoring commit date, inclusive (optional; unbounded by default)", "type": "string" } }, { "description": "RFC 3339 upper bound on the checkpoint's anchoring commit date, exclusive (optional; unbounded by default)", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339 upper bound on the checkpoint's anchoring commit date, exclusive (optional; unbounded by default)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCheckpointsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Checkpoints on a branch, with commit, diffstat, and sessions", "tags": [ "checkpoints" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/checkpoints/{checkpoint_id}": { "get": { "operationId": "repoCheckpointResolve", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "checkpoint_id", "required": true, "schema": { "type": "string" } }, { "description": "Branch the caller is viewing; drives needs_redirect, not which checkpoint resolves", "explode": false, "in": "query", "name": "branch", "schema": { "description": "Branch the caller is viewing; drives needs_redirect, not which checkpoint resolves", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointResolveOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A single checkpoint, with its branch membership", "tags": [ "checkpoints" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/checkpoints/{checkpoint_id}/analysis": { "get": { "description": "The stored analysis for a checkpoint. Its fields stay empty until the analysis worker has processed the checkpoint.", "operationId": "repoCheckpointAnalysis", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "checkpoint_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointAnalysisBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A checkpoint's LLM analysis", "tags": [ "checkpoints" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/checkpoints/{checkpoint_id}/transcript": { "get": { "operationId": "repoCheckpointTranscript", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "checkpoint_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointTranscriptOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A checkpoint's sessions as message trees", "tags": [ "checkpoints" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/checkpoints/{checkpoint_id}/transcript/raw": { "get": { "operationId": "repoCheckpointTranscriptRaw", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "checkpoint_id", "required": true, "schema": { "type": "string" } }, { "description": "Session index within the checkpoint", "explode": false, "in": "query", "name": "session", "schema": { "default": 0, "description": "Session index within the checkpoint", "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Stream a checkpoint session's raw transcript", "tags": [ "checkpoints" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/collaborators": { "get": { "description": "Every account with effective access to the repository, each with its best-effort GitHub handle and reader/writer role. Intended for building an author picker keyed on real account IDs rather than raw GitHub logins.", "operationId": "repoCollaborators", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Max collaborators per page", "explode": false, "in": "query", "name": "pageSize", "schema": { "description": "Max collaborators per page", "format": "int64", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Cursor from a previous page's nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Cursor from a previous page's nextPageToken", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCollaboratorsBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Accounts with effective access to the repository", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/commits": { "get": { "description": "Each commit embeds a preview of the checkpoints — the coding-agent work — linked to it, so you can see the work behind a commit without a second request.", "operationId": "repoCommits", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Branch to list; empty = the repo's default branch", "explode": false, "in": "query", "name": "branch", "schema": { "description": "Branch to list; empty = the repo's default branch", "type": "string" } }, { "description": "Opaque entiredb page token from a prior next_cursor", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque entiredb page token from a prior next_cursor", "type": "string" } }, { "description": "Page size, clamped to 1..200", "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "description": "Page size, clamped to 1..200", "format": "int64", "type": "integer" } }, { "description": "RFC 3339 lower bound on commit date (optional; unbounded by default)", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339 lower bound on commit date (optional; unbounded by default)", "type": "string" } }, { "description": "RFC 3339 upper bound on commit date (optional; unbounded by default)", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339 upper bound on commit date (optional; unbounded by default)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCommitsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Commits in a repository, with checkpoint previews", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/commits/{sha}": { "get": { "operationId": "repoCommitDetail", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Full 40- or 64-char hex commit SHA", "in": "path", "name": "sha", "required": true, "schema": { "description": "Full 40- or 64-char hex commit SHA", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitDetailOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "One commit, with diffstats and a checkpoint preview", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/commits/{sha}/check-runs": { "get": { "operationId": "listCheckRuns", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "sha", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "suite_key", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRunsResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List current check runs", "tags": [ "repos" ] }, "post": { "operationId": "writeCheckRuns", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "sha", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRunsWrite" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRunsWriteResult" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Upsert check runs", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/commits/{sha}/check-suites": { "get": { "operationId": "listCheckSuites", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "sha", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckSuitesResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List current check suites", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/commits/{sha}/checkpoints": { "get": { "operationId": "repoCommitCheckpoints", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "sha", "required": true, "schema": { "type": "string" } }, { "description": "Page size, clamped to 1..1000", "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "description": "Page size, clamped to 1..1000", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCheckpointsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Checkpoints linked to a commit, with commit, diffstat, and sessions", "tags": [ "checkpoints" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/commits:resolve-rows": { "post": { "description": "Resolves a batch of commit shas to rows with the same shape the commits list serves, including embedded checkpoint previews with resolved session names. The map is keyed by each sha exactly as requested; the row's own commitSha is the canonical lowercase form and may differ in case from its key — join on the key, not the row field. Unknown, garbage-collected, and malformed shas are absent from the map, so callers keep whatever fallback they already hold. Diff stats come from the same git computation the commits list serves (first-parent diff); a commit whose diff missed entiredb's per-commit budget carries null stats, exactly like the list. Checkpoint preview placement follows the requested sha set — a checkpoint anchors to its latest linking commit within the set — so a commit's previews can differ from the list page's placement. Built for search-result hydration: the search index stores only index-time text, and this read overlays live row data at query time.", "operationId": "repoCommitRowsResolve", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitRowsResolveInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitRowsResolveOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Resolve commit shas to commit list rows", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/compare": { "get": { "operationId": "repoCompare", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Base ref (branch name or commit SHA)", "explode": false, "in": "query", "name": "base", "schema": { "description": "Base ref (branch name or commit SHA)", "type": "string" } }, { "description": "Head ref (branch name or commit SHA)", "explode": false, "in": "query", "name": "head", "schema": { "description": "Head ref (branch name or commit SHA)", "type": "string" } }, { "description": "Page size, clamped to 1..200", "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "description": "Page size, clamped to 1..200", "format": "int64", "type": "integer" } }, { "description": "Commits to skip from the head-of-delta, clamped to 0..1000", "explode": false, "in": "query", "name": "offset", "schema": { "default": 0, "description": "Commits to skip from the head-of-delta, clamped to 0..1000", "format": "int64", "type": "integer" } }, { "description": "Comma-separated optional includes; only 'sessions' is supported", "explode": false, "in": "query", "name": "include", "schema": { "description": "Comma-separated optional includes; only 'sessions' is supported", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Compare two branches: commit delta, ahead/behind, and checkpoints", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/compare/contributors": { "get": { "operationId": "repoCompareContributors", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Base ref (branch name or commit SHA)", "explode": false, "in": "query", "name": "base", "schema": { "description": "Base ref (branch name or commit SHA)", "type": "string" } }, { "description": "Head ref (branch name or commit SHA)", "explode": false, "in": "query", "name": "head", "schema": { "description": "Head ref (branch name or commit SHA)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareContributorsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Commit authors across a branch comparison, with commit counts", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/contributors": { "get": { "operationId": "repoContributors", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "sort", "schema": { "default": "commits", "enum": [ "commits", "checkpoints", "tokens", "lines" ], "type": "string" } }, { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContributorsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Per-contributor leaderboard for a repository", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/experts": { "post": { "description": "Ranks the coding agents that worked on specific parts of a repository, with supporting evidence. You describe the code either as explicit paths or as a natural-language topic, but not both; the natural-language form needs a code-search index and is unavailable where none is configured.", "operationId": "repoExperts", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpertsInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpertsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Rank the agents that worked on a repository's files or paths", "tags": [ "experts" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/merge-preview": { "get": { "description": "Whether merging head into base would conflict, and which paths do. Computed as a dry run against a discarded in-memory tree — nothing is merged and nothing is stored. The answer holds only for the commits the two refs resolved to when it ran, which the response reports back, so a push to either ref invalidates it; it is served uncacheable and must not be replayed.", "operationId": "repoMergePreview", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Base ref (branch name)", "explode": false, "in": "query", "name": "base", "schema": { "description": "Base ref (branch name)", "type": "string" } }, { "description": "Head ref (branch, tag, or full commit SHA)", "explode": false, "in": "query", "name": "head", "schema": { "description": "Head ref (branch, tag, or full commit SHA)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergePreviewOutputBody" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Preview merging head into base: outcome and conflicted paths", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/meta": { "get": { "description": "Reads git-tracked metadata for a target within a namespace. The metadata lives in the repository's own git history — git is the source of truth — so a read reflects its current state and returns the namespace's current version, which you can carry into a conditional write.", "operationId": "repoGitMetaGet", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Metadata namespace: the complete ref sub-path under refs/meta/, e.g. entire/settings or records/planning/main", "explode": false, "in": "query", "name": "namespace", "required": true, "schema": { "description": "Metadata namespace: the complete ref sub-path under refs/meta/, e.g. entire/settings or records/planning/main", "type": "string" } }, { "description": "git-meta target: commit:\u003csha\u003e, branch:\u003cname\u003e, path:\u003cp\u003e, change-id:\u003cid\u003e, or project", "explode": false, "in": "query", "name": "target", "required": true, "schema": { "description": "git-meta target: commit:\u003csha\u003e, branch:\u003cname\u003e, path:\u003cp\u003e, change-id:\u003cid\u003e, or project", "type": "string" } }, { "description": "Exact key; omit to list all keys for the target", "explode": false, "in": "query", "name": "key", "schema": { "description": "Exact key; omit to list all keys for the target", "type": "string" } }, { "description": "Namespace filter, e.g. agent (returns agent and agent:*)", "explode": false, "in": "query", "name": "prefix", "schema": { "description": "Namespace filter, e.g. agent (returns agent and agent:*)", "type": "string" } }, { "description": "Max keys per page", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Max keys per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor from a previous page's nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Cursor from a previous page's nextPageToken", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoMetaReadOutputBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Read metadata keys for a target", "tags": [ "git-meta" ] }, "post": { "description": "Applies one edit to a target's metadata within a namespace, written into git as the source of truth. Writes use optimistic concurrency: read the current version, then write conditionally, so a concurrent change is rejected rather than silently overwritten.", "operationId": "repoGitMetaWrite", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Metadata namespace: the ref sub-path under refs/meta/ (e.g. entire/settings)", "explode": false, "in": "query", "name": "namespace", "required": true, "schema": { "description": "Metadata namespace: the ref sub-path under refs/meta/ (e.g. entire/settings)", "type": "string" } }, { "description": "Optimistic concurrency: apply only if the namespace's ETag still matches; \"*\" requires it to exist. Omit to apply unconditionally (merges onto the latest).", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: apply only if the namespace's ETag still matches; \"*\" requires it to exist. Omit to apply unconditionally (merges onto the latest).", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoMetaWriteInputBody" } } }, "required": true }, "responses": { "204": { "description": "No Content", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Set or remove metadata on a target", "tags": [ "git-meta" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/meta/targets": { "get": { "description": "Lists every path target at or beneath a path, with its metadata, in one pass. targetPath is segment-aligned rather than a string prefix, so records/pl selects nothing rather than matching records/plan. The whole scan is pinned to a single commit — given explicitly, or the namespace tip resolved on the first page — and the pageToken carries that commit along with the scan's filters, so later pages read the same tree even when the caller sends nothing but the token.", "operationId": "repoGitMetaListTargets", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Metadata namespace: the complete ref sub-path under refs/meta/, e.g. records/planning/main", "explode": false, "in": "query", "name": "namespace", "required": true, "schema": { "description": "Metadata namespace: the complete ref sub-path under refs/meta/, e.g. records/planning/main", "type": "string" } }, { "description": "Return every path target at or beneath this path, e.g. records/plan. Segment-aligned, not a string prefix: records/pl selects nothing rather than matching records/plan. Omit for every path target in the namespace.", "explode": false, "in": "query", "name": "targetPath", "schema": { "description": "Return every path target at or beneath this path, e.g. records/plan. Segment-aligned, not a string prefix: records/pl selects nothing rather than matching records/plan. Omit for every path target in the namespace.", "type": "string" } }, { "description": "Full commit OID to pin the whole scan to (typically a prior ETag). Must be a complete object id, not a branch, tag or abbreviation: the pin is reused across several upstream reads and across pages, so anything still needing resolution could resolve differently at each. Omit to pin the namespace tip resolved on the first page.", "explode": false, "in": "query", "name": "ref", "schema": { "description": "Full commit OID to pin the whole scan to (typically a prior ETag). Must be a complete object id, not a branch, tag or abbreviation: the pin is reused across several upstream reads and across pages, so anything still needing resolution could resolve differently at each. Omit to pin the namespace tip resolved on the first page.", "type": "string" } }, { "description": "Exact key; omit to list all keys", "explode": false, "in": "query", "name": "key", "schema": { "description": "Exact key; omit to list all keys", "type": "string" } }, { "description": "Key namespace filter, e.g. agent (returns agent and agent:*). Unrelated to targetPath.", "explode": false, "in": "query", "name": "prefix", "schema": { "description": "Key namespace filter, e.g. agent (returns agent and agent:*). Unrelated to targetPath.", "type": "string" } }, { "description": "Max targets per page. A target's keys are never split across pages.", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Max targets per page. A target's keys are never split across pages.", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor from a previous page's nextPageToken. Carries the pinned commit and the scan's scope, so continuation pages read the same tree with the same filters.", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Cursor from a previous page's nextPageToken. Carries the pinned commit and the scan's scope, so continuation pages read the same tree with the same filters.", "type": "string" } }, { "description": "Also report who last changed each target, derived from git history at the pinned commit. Costs one extra read per page.", "explode": false, "in": "query", "name": "includeAuthorship", "schema": { "description": "Also report who last changed each target, derived from git history at the pinned commit. Costs one extra read per page.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoMetaTargetsOutputBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List metadata for every target under a path", "tags": [ "git-meta" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/agent-activity": { "get": { "operationId": "repoOverviewAgentActivity", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "type": "string" } }, { "description": "IANA time zone: since/until and days are the viewer's local days (default UTC)", "explode": false, "in": "query", "name": "timeZone", "schema": { "description": "IANA time zone: since/until and days are the viewer's local days (default UTC)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoAgentActivityOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Daily per-agent checkpoint activity on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/branch-commit-dates": { "get": { "operationId": "repoOverviewBranchCommitDates", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "Branch name; repeat the param for multiple branches", "explode": true, "in": "query", "name": "branch", "schema": { "description": "Branch name; repeat the param for multiple branches", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "RFC3339/ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC3339/ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "RFC3339/ISO date; upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC3339/ISO date; upper bound on commit date (default unbounded)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoBranchCommitDatesOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Distinct commit-days per branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/checkpoint-metrics": { "get": { "operationId": "repoOverviewCheckpointMetrics", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "ISO date lower bound (inclusive); absent = unbounded", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date lower bound (inclusive); absent = unbounded", "type": "string" } }, { "description": "ISO date upper bound (inclusive); absent = unbounded", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date upper bound (inclusive); absent = unbounded", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCheckpointMetricsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Average per-checkpoint metrics on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/commit-stats": { "get": { "operationId": "repoOverviewCommitStats", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "type": "string" } }, { "description": "IANA time zone: since/until and days are the viewer's local days (default UTC)", "explode": false, "in": "query", "name": "timeZone", "schema": { "description": "IANA time zone: since/until and days are the viewer's local days (default UTC)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoCommitStatsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Commit and checkpoint stats on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/contributor-agents": { "get": { "operationId": "repoOverviewContributorAgents", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoContributorAgentsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Per-contributor commit totals and agent breakdown on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/contributor-tokens": { "get": { "operationId": "repoOverviewContributorTokens", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoContributorTokensOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Per-contributor token totals on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/contributors": { "get": { "operationId": "repoOverviewContributors", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoContributorsOverviewOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Per-contributor commit leaderboard on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/pr-stats": { "get": { "operationId": "repoOverviewPRStats", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on PR date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on PR date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on PR date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on PR date (default unbounded)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoPRStatsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Opened and merged PR counts, with a daily series", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/session-patterns": { "get": { "operationId": "repoOverviewSessionPatterns", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound on commit date (default unbounded)", "type": "string" } }, { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound on commit date (default unbounded)", "type": "string" } }, { "description": "IANA timezone for hour/weekday/date bucketing (default UTC)", "explode": false, "in": "query", "name": "timeZone", "schema": { "description": "IANA timezone for hour/weekday/date bucketing (default UTC)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSessionPatternsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Session timing, depth, and velocity patterns on the default branch", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/overview/tldr": { "get": { "description": "A generated prose summary of the repository — what it is for, what changed recently, and how to contribute. Served stale-while-revalidate: a summary that has aged out is returned as-is with `isRefreshing` set while a fresh one generates, and a repository with none yet returns the empty shape with `isPending` set. Poll while either flag is present. `hasSummary` reports whether this response carries one; `sources` reports what the generation actually read, so a thin summary is explicable.", "operationId": "repoOverviewTLDR", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoTLDROutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Generated overview summary for a repository", "tags": [ "overview" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/raw": { "get": { "description": "Returns one file's bytes at a ref, always as an inert text/plain attachment. A 404 carries code `ref_not_found` when the ref does not resolve (a new repository's default branch before its first push); a missing file at a resolved ref is a 404 without a code. A mirror's view can lag its source, so the code is not final there.", "operationId": "repoRawFile", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Ref or SHA to read at (defaults to HEAD when empty)", "explode": false, "in": "query", "name": "ref", "schema": { "description": "Ref or SHA to read at (defaults to HEAD when empty)", "type": "string" } }, { "description": "File path within the repo", "explode": false, "in": "query", "name": "path", "required": true, "schema": { "description": "File path within the repo", "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A file's contents at a ref", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/refs/events": { "get": { "description": "Streams live ref (branch/tag/HEAD) changes as they happen — a push, not a poll — with rapid updates to the same ref coalesced to at most one event roughly every 200ms. On connect you get a snapshot of current refs, then only changes from that point on; there is no history to replay, so a reconnect re-snapshots rather than catching up on what it missed.", "operationId": "repoRefEvents", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Ref-name prefixes to filter by (repeatable), e.g. \"refs/heads/\", \"refs/tags/\", \"HEAD\" — the same convention as GET /repos/{repo_id}/refs. Empty streams every ref.", "explode": true, "in": "query", "name": "prefix", "schema": { "description": "Ref-name prefixes to filter by (repeatable), e.g. \"refs/heads/\", \"refs/tags/\", \"HEAD\" — the same convention as GET /repos/{repo_id}/refs. Empty streams every ref.", "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } } ], "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Stream live ref (branch/tag/HEAD) change events for a repository", "tags": [ "refs" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/runner-admission": { "get": { "description": "Whether runs in the repository are currently refused, as core's runner admission would decide. Reading it changes nothing, so it is safe to poll. Billing refusals report paused_by billing without the reason; billing_subject is who pays for the repository's runs.", "operationId": "repoRunnerAdmission", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoRunnerAdmission" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get whether a repo's runs are paused", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runner-runs": { "get": { "description": "The repository's runs, most recently created first, addressed by opaque repo id, each with its token usage and the models it ran; trail_id narrows to one Trail's runs. Same processing-primary 404 as the wire-parity path.", "operationId": "runsListByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Opaque cursor from a prior nextPageToken", "type": "string" } }, { "description": "Only runs attached to this Trail (Trail id, ULID). A pageToken must be reused with the same trail_id.", "explode": false, "in": "query", "name": "trail_id", "schema": { "description": "Only runs attached to this Trail (Trail id, ULID). A pageToken must be reused with the same trail_id.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunsListResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a repo's runner runs (repo_id addressing)", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runner-runs/{runId}": { "delete": { "description": "Cancels a run, addressed by opaque repo id. Same admission rules, 409 and repo-scoping 404 as the wire-parity path.", "operationId": "runCancelByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Run id (ULID)", "in": "path", "name": "runId", "required": true, "schema": { "description": "Run id (ULID)", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Cancel a repo's runner run (repo_id addressing)", "tags": [ "trail-runs" ] }, "get": { "description": "A single run, addressed by opaque repo id, including its launch decisions (model, extraArgs, scopeJson). Same processing-primary and repo-scoping 404s as the wire-parity path.", "operationId": "runDetailByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Run id (ULID)", "in": "path", "name": "runId", "required": true, "schema": { "description": "Run id (ULID)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetailResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a repo's runner run (repo_id addressing)", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runner-settings": { "patch": { "operationId": "repoRunnerSettings", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerSettingsInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerSettingsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a repository's runner settings", "tags": [ "repo-settings" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runs": { "get": { "description": "Pages the runs in this repository of the agents of the project that owns it, newest first, archived agents' included. Each run is summarized without the Environment it pinned or the subject paying for it; GET /repos/{repo_id}/runs/{id} returns the whole run as the caller may read it. Requires pull on the repository.", "operationId": "repoRunsList", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } }, { "description": "Only runs of this agent.", "explode": false, "in": "query", "name": "agent_id", "schema": { "description": "Only runs of this agent.", "type": "string" } }, { "description": "Only runs on Changes of this product Trail.", "explode": false, "in": "query", "name": "trail_id", "schema": { "description": "Only runs on Changes of this product Trail.", "type": "string" } }, { "description": "Only runs on this Change.", "explode": false, "in": "query", "name": "change_id", "schema": { "description": "Only runs on this Change.", "type": "string" } }, { "description": "Only runs in this status.", "explode": false, "in": "query", "name": "status", "schema": { "description": "Only runs in this status.", "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor. Send it with the filters of the page that returned it; other filters are refused (400).", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor. Send it with the filters of the page that returned it; other filters are refused (400).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageRepositoryRun" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a repository's agent runs", "tags": [ "runs" ] }, "post": { "description": "Starts one run of the agent on a Change in this repository, as POST /{host}/{project}/agents/{id}/runs does. A Change in another repository reads as none (422). Requires pull on the repository, and push to start, retry or cancel; nothing of the project that owns it. billing_subject is returned only to the project's readers, events and diagnostic only with push or canManageAgents, and the agent's configuration only with canManageAgents.", "operationId": "repoRunsCreate", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } }, { "description": "Required. Repeating the identical request returns the run it first started, even after the agent was edited or archived; a different request under the key is 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Required. Repeating the identical request returns the run it first started, even after the agent was edited or archived; a different request under the key is 409.", "maxLength": 128, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryRunCreate" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "Accepted", "headers": { "Idempotency-Replayed": { "schema": { "description": "true when the Idempotency-Key named an earlier identical request, whose run is returned; omitted otherwise.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Run an agent on a repository's Change", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runs/{id}": { "get": { "description": "Returns one of the repository's runs as GET /{host}/{project}/runs/{id} does. Requires pull on the repository, and push to start, retry or cancel; nothing of the project that owns it. billing_subject is returned only to the project's readers, events and diagnostic only with push or canManageAgents, and the agent's configuration only with canManageAgents.", "operationId": "repoRunGet", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a repository's run", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runs/{id}/cancel": { "post": { "description": "Cancels one of the repository's runs, as POST /{host}/{project}/runs/{id}/cancel does. Requires pull on the repository, and push to start, retry or cancel; nothing of the project that owns it. billing_subject is returned only to the project's readers, events and diagnostic only with push or canManageAgents, and the agent's configuration only with canManageAgents.", "operationId": "repoRunCancel", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Cancel a repository's run", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runs/{id}/retry": { "post": { "description": "Starts the next attempt of one of the repository's runs, as POST /{host}/{project}/runs/{id}/retry does. Requires pull on the repository, and push to start, retry or cancel; nothing of the project that owns it. billing_subject is returned only to the project's readers, events and diagnostic only with push or canManageAgents, and the agent's configuration only with canManageAgents.", "operationId": "repoRunRetry", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } }, { "description": "Optional. Shares the run starts' key space: the same key cannot name both.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional. Shares the run starts' key space: the same key cannot name both.", "maxLength": 128, "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "Accepted", "headers": { "Idempotency-Replayed": { "schema": { "description": "true when the Idempotency-Key named an earlier identical request, whose run is returned; omitted otherwise.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Retry a repository's run", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/runs/{id}/snapshot": { "get": { "description": "Returns the snapshot one of the repository's runs was admitted with, as GET /{host}/{project}/runs/{id}/snapshot does. Requires pull on the repository, and push to start, retry or cancel; nothing of the project that owns it. billing_subject is returned only to the project's readers, events and diagnostic only with push or canManageAgents, and the agent's configuration only with canManageAgents.", "operationId": "repoRunSnapshotGet", "parameters": [ { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repository id (placement ULID or public repo_\u003cgroup ULID\u003e).", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a repository's run snapshot", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/secrets": { "get": { "description": "Which repository secrets are configured and when each was last set or rotated — metadata only, never the values. There is no endpoint that returns a stored secret value. Requires repo-admin (manage_settings), the same tier as setting one.", "operationId": "repoSecretsList", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Max keys per page", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Max keys per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor from a previous page's nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Cursor from a previous page's nextPageToken", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSecretsListOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List which repository secrets are configured", "tags": [ "repo-settings" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/secrets/{secretKey}": { "delete": { "description": "Deletes a repository secret, removing the stored ciphertext and its key from the live store; a backup taken before the deletion still holds them until it ages out. Idempotent — deleting a key that is not configured succeeds. Requires repo-admin (manage_settings).", "operationId": "repoSecretDelete", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "secretKey", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a repository secret", "tags": [ "repo-settings" ] }, "put": { "description": "Stores a repository secret (a customer-supplied model provider API key) encrypted at rest. Write-only: no endpoint ever returns the stored value — it can only be rotated (by setting it again) or deleted. The runner reads it in the repository's own cell, never over the API. Setting an existing key rotates it. Requires repo-admin (manage_settings): the stored key decides which account pays for the repository's model calls.", "operationId": "repoSecretSet", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "secretKey", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSecretPutInputBody" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Set or rotate a repository secret", "tags": [ "repo-settings" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/session/{session_id}/display-name": { "patch": { "operationId": "repoSessionRename", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRenameInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionRenameOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Set or clear a session's display name", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions": { "get": { "operationId": "repoSessions", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "description": "Set to all to include every historically linked repo session; omit for branch/default-branch or base/head reachability", "explode": false, "in": "query", "name": "scope", "schema": { "description": "Set to all to include every historically linked repo session; omit for branch/default-branch or base/head reachability", "enum": [ "all" ], "type": "string" } }, { "description": "Branch to filter to; empty = the repo's default branch", "explode": false, "in": "query", "name": "branch", "schema": { "description": "Branch to filter to; empty = the repo's default branch", "type": "string" } }, { "description": "Base branch or commit SHA to exclude; must be supplied with head and without branch", "explode": false, "in": "query", "name": "base", "schema": { "description": "Base branch or commit SHA to exclude; must be supplied with head and without branch", "type": "string" } }, { "description": "Head branch or commit SHA to include; must be supplied with base and without branch", "explode": false, "in": "query", "name": "head", "schema": { "description": "Head branch or commit SHA to include; must be supplied with base and without branch", "type": "string" } }, { "explode": false, "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "Page size, clamped to 1..200", "explode": false, "in": "query", "name": "limit", "schema": { "default": 50, "description": "Page size, clamped to 1..200", "format": "int64", "type": "integer" } }, { "description": "RFC 3339 lower bound on last_activity_at, inclusive (optional; unbounded by default)", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339 lower bound on last_activity_at, inclusive (optional; unbounded by default)", "type": "string" } }, { "description": "RFC 3339 upper bound on last_activity_at, exclusive (optional; unbounded by default — in practice capped 100 years out, an unreachable bound for any real session)", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339 upper bound on last_activity_at, exclusive (optional; unbounded by default — in practice capped 100 years out, an unreachable bound for any real session)", "type": "string" } }, { "description": "Include complete scoped author, agent, and model filter choices on the first page; ignored with cursor", "explode": false, "in": "query", "name": "includeFacets", "schema": { "description": "Include complete scoped author, agent, and model filter choices on the first page; ignored with cursor", "type": "boolean" } }, { "description": "Match any author facet key (repeatable or comma-separated)", "explode": true, "in": "query", "name": "authorFacet", "schema": { "description": "Match any author facet key (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude author facet keys (repeatable or comma-separated)", "explode": true, "in": "query", "name": "authorFacetNot", "schema": { "description": "Exclude author facet keys (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any agent (repeatable or comma-separated)", "explode": true, "in": "query", "name": "agent", "schema": { "description": "Match any agent (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude agents (repeatable or comma-separated)", "explode": true, "in": "query", "name": "agentNot", "schema": { "description": "Exclude agents (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any model (repeatable or comma-separated)", "explode": true, "in": "query", "name": "model", "schema": { "description": "Match any model (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude models (repeatable or comma-separated)", "explode": true, "in": "query", "name": "modelNot", "schema": { "description": "Exclude models (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match Review sessions when true, or non-Review sessions when false", "explode": false, "in": "query", "name": "isReview", "schema": { "description": "Match Review sessions when true, or non-Review sessions when false", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Case-insensitive literal substring over effective name, prompt, and agent", "explode": false, "in": "query", "name": "search", "schema": { "description": "Case-insensitive literal substring over effective name, prompt, and agent", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSessionsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Sessions in a repository", "tags": [ "sessions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions/{session_id}": { "get": { "operationId": "repoSessionDetail", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListItem" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A single session", "tags": [ "sessions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions/{session_id}/share": { "delete": { "description": "Stops sharing a session and discards its public snapshot. Idempotent — a no-op if the session was never shared.", "operationId": "repoSessionUnshare", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionShareOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Stop sharing a session publicly", "tags": [ "sessions" ] }, "post": { "description": "Makes a session publicly viewable and captures a snapshot of its transcript so it stays readable once shared. Idempotent — re-sharing refreshes the snapshot. In a private repository this works only after the repository's public-sharing setting has been enabled.", "operationId": "repoSessionShare", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionShareOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Share a session publicly", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions/{session_id}/subagents": { "get": { "operationId": "repoSessionSubagents", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum children to return (default 50, maximum 200)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Maximum children to return (default 50, maximum 200)", "format": "int64", "type": "integer" } }, { "description": "Opaque pagination cursor", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSubagentsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Subagent sessions launched by a parent session", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions/{session_id}/subagents/{subagent_id}/transcript": { "get": { "operationId": "repoSessionSubagentTranscript", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subagent_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSubagentTranscriptOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A subagent session transcript", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions/{session_id}/transcript": { "get": { "description": "A session's full transcript, merged across all of its checkpoints. When the session has been shared, it is served from that public snapshot, so it stays readable after sharing.", "operationId": "repoSessionTranscript", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTranscriptOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "A session's full transcript as a message tree", "tags": [ "sessions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions/{session_id}/transcript/raw": { "get": { "description": "The raw log is taken from the session's latest contributing checkpoint, not merged across all of them.", "operationId": "repoSessionTranscriptRaw", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Stream a session's raw transcript", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/sessions:resolve-names": { "post": { "description": "Resolves a batch of session ids to their effective display names and full list rows, read live from the sessions table. `names` maps each known id to its resolved name (custom override, then AI-generated, then the heuristic); `sessions` maps it to the same item shape the sessions list returns. Unknown ids are absent from both maps, so callers keep whatever fallback they already hold. Built for search-result hydration: the search index stores only index-time heuristics, and this read overlays the current names and row data at query time. Row items carry the stored ingest-time author login; this read performs no live identity resolve (the search caller renders authors from its own index), so it stays cell-local.", "operationId": "repoSessionResolveNames", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNamesResolveInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNamesResolveResult" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Resolve sessions' effective display names and list rows", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/settings/public-sharing": { "patch": { "description": "The repository-wide opt-in that lets individual sessions in a private repository be shared publicly. Turning it off retracts that visibility, even for sessions already shared.", "operationId": "repoPublicSharing", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSharingInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSharingOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Turn repository-wide public sharing on or off", "tags": [ "repo-settings" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/summary": { "get": { "operationId": "repoSummary", "parameters": [ { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID, public repo_\u003cgroup ULID\u003e, or audience slug", "type": "string" } }, { "description": "Relative window", "explode": false, "in": "query", "name": "timeframe", "schema": { "default": "last-6-months", "description": "Relative window", "enum": [ "last-month", "last-3-months", "last-6-months" ], "type": "string" } }, { "description": "RFC 3339; overrides timeframe start", "explode": false, "in": "query", "name": "since", "schema": { "description": "RFC 3339; overrides timeframe start", "type": "string" } }, { "description": "RFC 3339; overrides timeframe end", "explode": false, "in": "query", "name": "until", "schema": { "description": "RFC 3339; overrides timeframe end", "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 500, "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSummaryOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Headline activity rollup for a repository", "tags": [ "repos" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trail-settings": { "patch": { "operationId": "repoTrailSettings", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailSettingsInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailSettingsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a repository's trail settings", "tags": [ "repo-settings" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails": { "get": { "description": "The repository's trails addressed by repo id, ordered by updated_at descending, then id descending. Cursors restore active filters and ordering without freezing a snapshot. Repeated filters must match the cursor. Callers without access receive 403; authorized callers receive 404 when trails are unavailable.", "operationId": "trailsListByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor; restores filters and ordering. Authorization is checked again on every request.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor; restores filters and ordering. Authorization is checked again on every request.", "type": "string" } }, { "description": "Alias for id[eq]; repository-scoped Trail ULIDs.", "explode": true, "in": "query", "name": "id", "schema": { "description": "Alias for id[eq]; repository-scoped Trail ULIDs.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any Trail ULID; repeatable or comma-separated.", "explode": true, "in": "query", "name": "id[eq]", "schema": { "description": "Match any Trail ULID; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude Trail ULIDs; repeatable or comma-separated.", "explode": true, "in": "query", "name": "id[ne]", "schema": { "description": "Exclude Trail ULIDs; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for status[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status", "schema": { "description": "Alias for status[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any lifecycle status; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[eq]", "schema": { "description": "Match any lifecycle status; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude lifecycle statuses; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[ne]", "schema": { "description": "Exclude lifecycle statuses; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for priority[eq].", "explode": true, "in": "query", "name": "priority", "schema": { "description": "Alias for priority[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any priority; repeatable or comma-separated.", "explode": true, "in": "query", "name": "priority[eq]", "schema": { "description": "Match any priority; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude priorities; repeatable or comma-separated.", "explode": true, "in": "query", "name": "priority[ne]", "schema": { "description": "Exclude priorities; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for type[eq].", "explode": true, "in": "query", "name": "type", "schema": { "description": "Alias for type[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any Trail type; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[eq]", "schema": { "description": "Match any Trail type; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude Trail types; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[ne]", "schema": { "description": "Exclude Trail types; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for author[eq].", "explode": true, "in": "query", "name": "author", "schema": { "description": "Alias for author[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any author account ULID; repeatable or comma-separated.", "explode": true, "in": "query", "name": "author[eq]", "schema": { "description": "Match any author account ULID; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude author account ULIDs; repeatable or comma-separated.", "explode": true, "in": "query", "name": "author[ne]", "schema": { "description": "Exclude author account ULIDs; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for assignee[eq].", "explode": true, "in": "query", "name": "assignee", "schema": { "description": "Alias for assignee[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any assignee account ULID; repeatable or comma-separated.", "explode": true, "in": "query", "name": "assignee[eq]", "schema": { "description": "Match any assignee account ULID; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude assignee account ULIDs; repeatable or comma-separated.", "explode": true, "in": "query", "name": "assignee[ne]", "schema": { "description": "Exclude assignee account ULIDs; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for phase[eq].", "explode": true, "in": "query", "name": "phase", "schema": { "description": "Alias for phase[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any derived phase: planning, building, reviewing; repeatable or comma-separated.", "explode": true, "in": "query", "name": "phase[eq]", "schema": { "description": "Match any derived phase: planning, building, reviewing; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude derived phases: planning, building, reviewing; repeatable or comma-separated.", "explode": true, "in": "query", "name": "phase[ne]", "schema": { "description": "Exclude derived phases: planning, building, reviewing; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for display_status[eq].", "explode": true, "in": "query", "name": "display_status", "schema": { "description": "Alias for display_status[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match the union of lifecycle statuses (draft, merged, closed) and phases (planning, building, reviewing); repeatable or comma-separated. Planning-or-merged matches either condition.", "explode": true, "in": "query", "name": "display_status[eq]", "schema": { "description": "Match the union of lifecycle statuses (draft, merged, closed) and phases (planning, building, reviewing); repeatable or comma-separated. Planning-or-merged matches either condition.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude the union of lifecycle-status and phase matches: draft, planning, building, reviewing, merged, closed.", "explode": true, "in": "query", "name": "display_status[ne]", "schema": { "description": "Exclude the union of lifecycle-status and phase matches: draft, planning, building, reviewing, merged, closed.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Case-insensitive substring search over title, branch and original_branch.", "explode": false, "in": "query", "name": "q", "schema": { "description": "Case-insensitive substring search over title, branch and original_branch.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailsListResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a repo's trails (repo_id addressing)", "tags": [ "trails" ], "x-entire-published": true }, "post": { "description": "Creates a trail via the opaque repo id path; behaviour matches the wire-parity create (including the same status policy), and the Location header points back into this addressing scheme.", "operationId": "trailsCreateByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailCreateRequestJSON" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailCreateResponseBody" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create a trail by repo id", "tags": [ "trails" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/gate-settings": { "get": { "operationId": "trailsGateSettingsGetByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSettingsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get the repo's gate settings (repo_id addressing)", "tags": [ "trail-gates" ] }, "patch": { "operationId": "trailsGateSettingsPatchByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSettingsPatchBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSettingsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update the repo's gate settings (repo_id addressing)", "tags": [ "trail-gates" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/gates": { "get": { "description": "Returns the repository's gate configuration via the opaque repo id path, including disabled gates, editable configuration, and gatesEnabled. Same built-in initialization and availability while gate enforcement is disabled as the host-addressed route.", "operationId": "trailGateConfigByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailGateConfigResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get repository gate configuration (repo_id addressing)", "tags": [ "trail-gates" ] }, "post": { "description": "Creates a gate definition via the opaque repo id path. Same near-universal 409 as the wire-parity route — see its description.", "operationId": "trailsGateDefinitionCreateByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateDefinitionCreateBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateDefinitionCreateOutputBody" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create a repository gate definition (repo_id addressing)", "tags": [ "trail-gates" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/gates/{gateId}": { "delete": { "description": "Deletes a gate definition via the opaque repo id path. Same built-in delete-protection as the wire-parity route.", "operationId": "trailsGateDefinitionDeleteByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Gate definition id (ULID)", "in": "path", "name": "gateId", "required": true, "schema": { "description": "Gate definition id (ULID)", "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"...\") from a prior read/write of this gate. A mismatch is a 412; omit to delete unconditionally.", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"...\") from a prior read/write of this gate. A mismatch is a 412; omit to delete unconditionally.", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a repository gate definition (repo_id addressing)", "tags": [ "trail-gates" ] }, "patch": { "description": "Updates a gate definition via the opaque repo id path, with the same partial config-merge semantics as the wire-parity route.", "operationId": "trailsGateDefinitionPatchByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Gate definition id (ULID)", "in": "path", "name": "gateId", "required": true, "schema": { "description": "Gate definition id (ULID)", "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"...\") from a prior read/write of this gate. A mismatch is a 412; omit to apply unconditionally.", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"...\") from a prior read/write of this gate. A mismatch is a 412; omit to apply unconditionally.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateDefinitionPatchBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateDefinitionOutputBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a repository gate definition (repo_id addressing)", "tags": [ "trail-gates" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/linked-branches": { "get": { "description": "Every branch claimed by any trail in the repository, regardless of status, addressed by opaque repo id.", "operationId": "trailsLinkedBranchesByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailsLinkedBranchesBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Branches claimed by trails (repo_id addressing)", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/stats": { "get": { "description": "Trail counts bucketed by the four canonical statuses, addressed by opaque repo id. The total also counts legacy statuses that fit no bucket.", "operationId": "trailsStatsByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "ISO date; inclusive lower bound for window activity. With until, adds window to the response.", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO date; inclusive lower bound for window activity. With until, adds window to the response.", "type": "string" } }, { "description": "ISO date; inclusive upper bound for window activity. A bare date covers that whole day in time_zone.", "explode": false, "in": "query", "name": "until", "schema": { "description": "ISO date; inclusive upper bound for window activity. A bare date covers that whole day in time_zone.", "type": "string" } }, { "description": "IANA timezone for the window's daily buckets (default UTC)", "explode": false, "in": "query", "name": "time_zone", "schema": { "description": "IANA timezone for the window's daily buckets (default UTC)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailsStatsBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Trail counts by status (repo_id addressing)", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}": { "delete": { "deprecated": true, "description": "Deprecated: mark the trail as closed instead (status \"closed\"). Deletes the trail via the opaque repo id path, with the same conditional behaviour and Owned-Change rejection.", "operationId": "trailsDeleteByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a trail by repo id", "tags": [ "trails" ] }, "get": { "description": "A single trail by number, addressed by opaque repo id. Same fields and composition boundary as the wire-parity path.", "operationId": "trailDetailByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDetailResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a trail by number (repo_id addressing)", "tags": [ "trails" ], "x-entire-published": true }, "patch": { "description": "Updates trail metadata via the opaque repo id path, with the same status policy and optional If-Match conditional behaviour.", "operationId": "trailsUpdateByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailUpdateRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailUpdateResponseBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a trail's metadata by repo id", "tags": [ "trails" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/approvals": { "get": { "operationId": "trailsApprovalsByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailApprovalsResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a trail's recorded approval decisions (repo_id addressing)", "tags": [ "trail-approvals" ], "x-entire-published": true }, "post": { "operationId": "trailsApprovalsSubmitByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailApprovalSubmitRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailApprovalSubmitResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Submit an approval decision on a trail (repo_id addressing)", "tags": [ "trail-approvals" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/attachments": { "get": { "operationId": "trailsAttachmentsListByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentListResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List trail attachments (repo_id addressing)", "tags": [ "trail-attachments" ] }, "post": { "description": "Begins an attachment upload via the opaque repo id path; behaviour matches the wire-parity intent.", "operationId": "trailsAttachmentIntentByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Optional replay-safe key; a retried upload-intent resolves to the same attachment with a fresh presigned URL.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional replay-safe key; a retried upload-intent resolves to the same attachment with a fresh presigned URL.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentIntentBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentIntentResponseBody" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Begin a trail attachment upload (repo_id addressing)", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/attachments/{attachmentId}": { "delete": { "description": "Deletes an attachment via the opaque repo id path, with the same idempotent behaviour.", "operationId": "trailsAttachmentDeleteByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Attachment id (ULID)", "in": "path", "name": "attachmentId", "required": true, "schema": { "description": "Attachment id (ULID)", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a trail attachment (repo_id addressing)", "tags": [ "trail-attachments" ] }, "get": { "description": "Redirects to a presigned download URL via the opaque repo id path, with the same readiness behaviour.", "operationId": "trailsAttachmentServeByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Attachment id (ULID)", "in": "path", "name": "attachmentId", "required": true, "schema": { "description": "Attachment id (ULID)", "type": "string" } } ], "responses": { "302": { "description": "Found", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Serve a ready trail attachment (repo_id addressing)", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/attachments/{attachmentId}/complete": { "post": { "description": "Confirms an uploaded attachment via the opaque repo id path, with the same verification and outcomes.", "operationId": "trailsAttachmentCompleteByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Attachment id (ULID)", "in": "path", "name": "attachmentId", "required": true, "schema": { "description": "Attachment id (ULID)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentCompleteResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Confirm a trail attachment upload (repo_id addressing)", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/body-document/ensure": { "post": { "description": "Ensures the trail's body editor document exists, addressed by opaque repo id: same status, Location and gate semantics as the host-addressed route. This is the only addressing that reaches et-native repos — the host path resolves GitHub-mirrored names only, so their editor cannot be opened any other way.", "operationId": "trailBodyDocumentEnsureByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailBodyDocumentJSON" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Ensure a trail's body editor document exists (repo_id addressing)", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/branch": { "delete": { "description": "Answers 204 once the branch is gone, including a branch that was already gone. Open and draft Trails based on the branch are first moved to the base the Trail was merged into, as the caller. A kept branch answers 409 with `code` set to why: moved, protected, default_branch, stacked (a Trail based on it could not be moved) or base; a branch name another Trail has taken answers 409 with `code` branch_claimed, and a merge still finishing 409 with merge_in_progress. A refusal answers 422 or 503 with `code` set to its reason. A branch state that could not be read, a move of a Trail based on it that failed, and any other storage failure carry `code` failed.", "operationId": "trailsDeleteBranchByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a merged native Trail's branch at its saved head", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/ci-pr": { "post": { "description": "Ensures a Trail has a CI pull request via the opaque repo id path; behaviour, claim protection, 201 response, and Location match the host-addressed route.", "operationId": "trailsCreateCIPrByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailCIPrResponse" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create or link a CI pull request for a Trail, by repo id", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/discussions": { "get": { "operationId": "trailDiscussionsListByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior next_cursor", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a prior next_cursor", "type": "string" } }, { "description": "Embed each discussion's messages, as the detail route returns them", "explode": false, "in": "query", "name": "include_messages", "schema": { "description": "Embed each discussion's messages, as the detail route returns them", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionsListResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a trail's discussions (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "post": { "operationId": "trailDiscussionsCreateByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionCreateRequestJSON" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionCreateResponseBody" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Start a new discussion (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/discussions/stream": { "get": { "operationId": "trailDiscussionEventsStreamByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "description": "Return events with id strictly greater than this (non-negative integer).", "explode": false, "in": "query", "name": "after", "schema": { "description": "Return events with id strictly greater than this (non-negative integer).", "type": "string" } }, { "description": "Page size (default 200, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 200, capped at 1000).", "type": "string" } }, { "description": "text/event-stream streams events as SSE; otherwise a JSON page is returned.", "in": "header", "name": "Accept", "schema": { "description": "text/event-stream streams events as SSE; otherwise a JSON page is returned.", "type": "string" } }, { "description": "SSE resume cursor (falls back to ?after=); non-negative integer.", "in": "header", "name": "Last-Event-ID", "schema": { "description": "SSE resume cursor (falls back to ?after=); non-negative integer.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionEventsResponseBody" } }, "text/event-stream": { "schema": { "type": "string" } } }, "description": "JSON event page or SSE stream" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List or stream a trail's discussion events (repo_id addressing)", "tags": [ "trail-discussions" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/discussions/{discussion_id}": { "get": { "operationId": "trailDiscussionDetailByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionDetailResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a discussion and its messages (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "patch": { "operationId": "trailDiscussionUpdateByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionUpdateRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionUpdateResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a discussion's title/resolved state (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/discussions/{discussion_id}/messages": { "post": { "operationId": "trailDiscussionMessageCreateByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageCreateRequestJSON" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageResponseBody" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Add a message to a discussion (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/discussions/{discussion_id}/messages/{message_id}": { "delete": { "operationId": "trailDiscussionMessageDeleteByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a message (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "patch": { "operationId": "trailDiscussionMessageUpdateByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageUpdateRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Edit a message (repo_id addressing)", "tags": [ "trail-discussions" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/events": { "get": { "description": "Returns trail events by opaque repo id with the same JSON cursor pagination, category filters, open event catalog, and Last-Event-ID SSE resume as the name-addressed route.", "operationId": "trailEventsByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "description": "Alias for type[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type", "schema": { "description": "Alias for type[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match runner, monitor, or finding categories; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[eq]", "schema": { "description": "Match runner, monitor, or finding categories; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude runner, monitor, or finding categories; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[ne]", "schema": { "description": "Exclude runner, monitor, or finding categories; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Opaque JSON-page continuation. Filters may be omitted or repeated with matching values.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque JSON-page continuation. Filters may be omitted or repeated with matching values.", "type": "string" } }, { "description": "JSON page size: default 200, capped at 1000; zero returns an empty page.", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "JSON page size: default 200, capped at 1000; zero returns an empty page.", "type": "string" } }, { "description": "Numeric resume cursor: for SSE, used when Last-Event-ID is absent; for JSON pages, an alternative first-page start to cursor (mutually exclusive with cursor).", "explode": false, "in": "query", "name": "after", "schema": { "description": "Numeric resume cursor: for SSE, used when Last-Event-ID is absent; for JSON pages, an alternative first-page start to cursor (mutually exclusive with cursor).", "type": "string" } }, { "description": "text/event-stream streams events; otherwise returns a JSON page.", "in": "header", "name": "Accept", "schema": { "description": "text/event-stream streams events; otherwise returns a JSON page.", "type": "string" } }, { "description": "SSE numeric resume cursor; falls back to after.", "in": "header", "name": "Last-Event-ID", "schema": { "description": "SSE numeric resume cursor; falls back to after.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewEventsResponseBody" } }, "text/event-stream": { "schema": { "type": "string" } } }, "description": "JSON event page or SSE stream" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List or stream trail events (repo_id addressing)", "tags": [ "trail-activity" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/gates": { "get": { "description": "Evaluates configured gates using persisted checks results. mergeable indicates whether these gates allow merging; it does not include merge conflicts or guarantee fresh CI evidence. Use /mergeability for current merge readiness.", "operationId": "trailsGatesByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailGatesResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get the configurable gate evaluation for a trail (repo_id addressing)", "tags": [ "trail-gates" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/gates/recompute": { "post": { "description": "Forces a single trail's builtin gate results (up_to_date and approvals) to be recomputed against entiredb's current mirror compare and locally-stored review data, right now, with no forge call at all. The trail must be open with a linked branch and a known head, or this returns 422. checks is deliberately excluded — it stays covered by its own dedicated trigger, the check-run-completed webhook — so this route never touches base, ahead-by/has_code_changes, review-comment staleness, findings, or the checks gate; its only effect is the up_to_date/approvals recompute itself, returned as the resulting gate state.", "operationId": "trailsGateRecomputeByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailsGateRecomputeResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Force a single trail's builtin gate results to be recomputed, by repo id", "tags": [ "trail-gates" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/merge": { "post": { "operationId": "trailsMergeSubmitByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailMergeSubmitBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailMergeSubmitResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Merge a Trail (repo_id addressing)", "tags": [ "trail-approvals" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/mergeability": { "get": { "operationId": "trailsMergeabilityByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailMergeabilityResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get merge readiness for a trail (repo_id addressing)", "tags": [ "trail-approvals" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/monitors": { "get": { "operationId": "trailMonitorsByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailMonitorsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Trail monitor results (repo_id addressing)", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/restore-branch": { "post": { "operationId": "trailsRestoreBranchByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailRestoreBranchResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Restore a merged native Trail's branch at its saved head", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/review-rerun": { "post": { "description": "Re-runs every configured native review runner against the trail's current head. Already active same-head runs and completed reviews are preserved rather than duplicated; only newly accepted runs count in the response. If any runner's run is recorded failed at launch because its prompt is over the 64 KiB launch limit or the owner has spent Entire's model-key budget, the response is 422 with the message that run records, even when other runners launched. A launch refused for billing answers 422 with a message saying what to do next, and records no run.", "operationId": "reviewRerun", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRerunBody" } } }, "description": "Review re-run accepted or already complete" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Re-run configured native review runners", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews": { "post": { "operationId": "reviewStartByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewStartRequestJSON" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartReviewResponseBody" } } }, "description": "Created", "headers": { "Idempotency-Replayed": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Start a code review (repo_id addressing)", "tags": [ "trail-reviews" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews/comments": { "get": { "operationId": "trailReviewCommentsListByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "description": "Alias for status[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status", "schema": { "description": "Alias for status[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "explode": true, "in": "query", "name": "status[eq]", "schema": { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[ne]", "schema": { "description": "Exclude these statuses; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for severity[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "severity", "schema": { "description": "Alias for severity[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of high, medium, low.", "explode": true, "in": "query", "name": "severity[eq]", "schema": { "description": "Match any of high, medium, low.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these severities; comments without a severity remain eligible.", "explode": true, "in": "query", "name": "severity[ne]", "schema": { "description": "Exclude these severities; comments without a severity remain eligible.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "current (default), stale, or any; retained by the cursor.", "explode": false, "in": "query", "name": "stale", "schema": { "description": "current (default), stale, or any; retained by the cursor.", "type": "string" } }, { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "explode": false, "in": "query", "name": "include_dismissed", "schema": { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "type": "string" } }, { "description": "Page size (default 100, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 100, capped at 1000).", "type": "string" } }, { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsPage" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List all review comments for a trail (repo_id addressing)", "tags": [ "trail-reviews" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews/{review_id}": { "get": { "description": "A review's current state, addressed by opaque repo id. Same projection, counts, keyset paging, and event cursor as the wire-parity path.", "operationId": "reviewSnapshotByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Include dismissed comments when exactly true; retained by the cursor.", "explode": false, "in": "query", "name": "include_dismissed", "schema": { "description": "Include dismissed comments when exactly true; retained by the cursor.", "type": "string" } }, { "description": "current (default), stale, or any. Unrecognized values mean current; retained by the cursor.", "explode": false, "in": "query", "name": "stale", "schema": { "description": "current (default), stale, or any. Unrecognized values mean current; retained by the cursor.", "type": "string" } }, { "description": "Page size (default 100, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 100, capped at 1000).", "type": "string" } }, { "description": "Opaque continuation cursor; restores filters and ordering. Repeated filters must match.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor; restores filters and ordering. Repeated filters must match.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewSnapshotResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get review state (repo_id addressing)", "tags": [ "trail-reviews" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews/{review_id}/comments": { "get": { "description": "A review's comments, addressed by opaque repo id, with the same filters and event cursor as the wire-parity path.", "operationId": "reviewCommentsListByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Alias for status[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status", "schema": { "description": "Alias for status[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "explode": true, "in": "query", "name": "status[eq]", "schema": { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[ne]", "schema": { "description": "Exclude these statuses; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for severity[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "severity", "schema": { "description": "Alias for severity[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of high, medium, low.", "explode": true, "in": "query", "name": "severity[eq]", "schema": { "description": "Match any of high, medium, low.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these severities; comments without a severity remain eligible.", "explode": true, "in": "query", "name": "severity[ne]", "schema": { "description": "Exclude these severities; comments without a severity remain eligible.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "current (default), stale, or any; retained by the cursor.", "explode": false, "in": "query", "name": "stale", "schema": { "description": "current (default), stale, or any; retained by the cursor.", "type": "string" } }, { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "explode": false, "in": "query", "name": "include_dismissed", "schema": { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "type": "string" } }, { "description": "Page size (default 100, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 100, capped at 1000).", "type": "string" } }, { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsPage" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List comments for a review (repo_id addressing)", "tags": [ "trail-reviews" ] }, "post": { "operationId": "reviewCommentsByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsAtomicResponseBody" } } }, "description": "OK", "headers": { "Idempotency-Replayed": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Atomically publish review comments and summary (repo_id addressing)", "tags": [ "trail-reviews" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews/{review_id}/comments/{comment_id}": { "get": { "operationId": "reviewCommentGetByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "comment_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentJSON" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a review comment (repo_id addressing)", "tags": [ "trail-reviews" ] }, "patch": { "operationId": "reviewCommentPatchByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "comment_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentPatchRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentJSON" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a review comment (repo_id addressing)", "tags": [ "trail-reviews" ], "x-entire-published": true }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews/{review_id}/diff": { "get": { "description": "The per-file diff of the code a review pins, resolved through the git source. The base is the code_version's stored merge base, or derived from its base ref when absent; a review whose head or base can't be resolved is a 409. Patches are attached best-effort and dropped (with the file flagged) when the whole diff exceeds the read cap.", "operationId": "reviewDiffByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDiffResponseBody" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Diff of the code reviewed by a review (repo_id addressing)", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/reviews/{review_id}/files": { "get": { "description": "File contents at the reviewed code_version's head SHA. A path that is missing, too large, or unreadable comes back as a null entry rather than failing the request; the batch is bounded by an aggregate byte budget.", "operationId": "reviewFilesByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated file paths to read at the code_version head SHA (max 200).", "explode": false, "in": "query", "name": "paths", "schema": { "description": "Comma-separated file paths to read at the code_version head SHA (max 200).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewFilesResponseBody" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "File contents for the code reviewed by a review (repo_id addressing)", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/runs/{runnerId}": { "get": { "operationId": "trailRunByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Configured runner id (e.g. trail-semantic-diff)", "in": "path", "name": "runnerId", "required": true, "schema": { "description": "Configured runner id (e.g. trail-semantic-diff)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailRunResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Latest configured trail runner result (repo_id addressing)", "tags": [ "trail-runs" ] }, "post": { "description": "Starts the requested configured trail runner against the trail's current head. Repeating a request while that runner is active returns the existing run with outcome already_in_progress; outcome already_complete means a completed review already covers this head and nothing new launched. A run recorded failed at launch without a sandbox answers 422 with the message the run records. That happens when its prompt is over the 64 KiB launch limit, or when the repository's owner has spent Entire's model-key budget and the repository has no key of its own for that agent. A launch refused for billing (the free trial is used up, a monthly spend limit was reached, or billing is suspended) also answers 422, with a message saying what to do next and a code naming the reason, and records no run. A runner that only declares the push trigger (not api) is refused with 409 unless its own latest run for this trail already failed, timed out, or was canceled — this route only ever retries a real prior failure for that runner, it never grants it unconditional manual launching — and that retry is scoped to native review runners (trails_review-enabled); a merged/closed trail or one with no valid head is refused with 422, matching review-rerun's own admission.", "operationId": "manualTrailRunnerLaunch", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Repo-authored runner id", "in": "path", "name": "runnerId", "required": true, "schema": { "description": "Repo-authored runner id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualTrailRunnerLaunchBody" } } }, "description": "Accepted, already in progress, or already complete (outcome: accepted, already_in_progress, already_complete)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Launch a configured trail runner", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/stack": { "get": { "operationId": "trailsStackByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailStackResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a trail's forge stack membership (repo_id addressing)", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/timeline": { "get": { "description": "The trail's merged event timeline, newest first, cursor-paginated. Lifecycle, message, review, and commit events are merged into one ordered stream; commits are read through from git. commitCount is omitted and incomplete is true when the commit read-through degraded.", "operationId": "trailsTimelineByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Opaque cursor from a prior nextPageToken", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailTimelineResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a trail's merged event timeline (repo_id addressing)", "tags": [ "trail-activity" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/update-branch": { "post": { "description": "Updates an open Entire-native Trail branch by merging its base branch into it through the repository's native git storage. Both branch tips are fenced at their resolved SHAs, so a concurrent push is rejected rather than silently included; content conflicts leave the branch unchanged and must be resolved manually.", "operationId": "trailsUpdateBranchByRepoID", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailUpdateBranchResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update an Entire-native Trail branch from its base", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/trails/{number}/watchers": { "get": { "operationId": "trailWatchersByRepoID", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailWatchersBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List live watchers on a trail (repo_id addressing)", "tags": [ "trail-activity" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/tree": { "get": { "description": "Lists the repository tree at a ref, in the data plane's wire shape. A 404 carries code `ref_not_found` when the ref does not resolve (a new repository's default branch before its first push) and `path_not_found` when the ref resolves but the path does not; other codes name other read misses, and a 404 without a code is unclassified. A mirror's view can lag its source, so neither code is final there.", "operationId": "repoTree", "parameters": [ { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "in": "path", "name": "repo_id", "required": true, "schema": { "description": "Repo id: placement ULID or public repo_\u003cgroup ULID\u003e", "type": "string" } }, { "description": "Ref or SHA to list at (defaults to HEAD when empty)", "explode": false, "in": "query", "name": "ref", "schema": { "description": "Ref or SHA to list at (defaults to HEAD when empty)", "type": "string" } }, { "description": "Subtree to list; empty lists the root", "explode": false, "in": "query", "name": "path", "schema": { "description": "Subtree to list; empty lists the root", "type": "string" } }, { "description": "Walk the whole subtree", "explode": false, "in": "query", "name": "recursive", "schema": { "description": "Walk the whole subtree", "type": "boolean" } } ], "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Directory tree at a ref", "tags": [ "code" ] }, "x-upstream": "activity" }, "/repos/{repo_id}/watchers": { "get": { "operationId": "repoWatchers", "parameters": [ { "in": "path", "name": "repo_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoWatchersBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List live watchers for all trails in a repo", "tags": [ "trail-activity" ] }, "x-upstream": "activity" }, "/runner-runs/{host}/{owner}/{repo}": { "get": { "description": "The repository's runs, most recently created first, each with its token usage and the models it ran; trail_id narrows to one Trail's runs. A cell that isn't the repo group's processing primary 404s rather than serving an empty list.", "operationId": "runsList", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior nextPageToken", "explode": false, "in": "query", "name": "pageToken", "schema": { "description": "Opaque cursor from a prior nextPageToken", "type": "string" } }, { "description": "Only runs attached to this Trail (Trail id, ULID). A pageToken must be reused with the same trail_id.", "explode": false, "in": "query", "name": "trail_id", "schema": { "description": "Only runs attached to this Trail (Trail id, ULID). A pageToken must be reused with the same trail_id.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunsListResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a repo's runner runs", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/runner-runs/{host}/{owner}/{repo}/{runId}": { "delete": { "description": "Cancels a run at the user's request: the run and its latest prompt go terminal immediately, and the runner releases the sandbox the next time any of its handlers observes the canceled status. Canceled outranks every later terminal write, so a run whose prompt finishes moments afterwards cannot report success over the top of it. Answers 204 with no body — including for a run that had already settled on its own, since it too is stopped; read the run to see which status it settled on. A run still being provisioned 409s and can be cancelled again a moment later.", "operationId": "runCancel", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Run id (ULID)", "in": "path", "name": "runId", "required": true, "schema": { "description": "Run id (ULID)", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Cancel a repo's runner run", "tags": [ "trail-runs" ] }, "get": { "description": "A single run: its status and metadata, its token usage and the models it ran, its launch decisions (model, extraArgs, scopeJson), its full prompt history, its event timeline (capped at 200), and the automation result its output_config names. A cell that isn't the repo group's processing primary 404s, as does a run id that doesn't belong to this repository.", "operationId": "runDetail", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Run id (ULID)", "in": "path", "name": "runId", "required": true, "schema": { "description": "Run id (ULID)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetailResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a repo's runner run", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/runner/.well-known/jwks.json": { "get": { "description": "Returns the active and rotation-overlap public signing keys for runner assertions.", "operationId": "runnerIssuerJWKS", "responses": { "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Error" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONWebKeySet" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } } }, "security": [], "summary": "Runner issuer JSON Web Key Set", "tags": [ "runner-issuer" ] }, "x-upstream": "activity" }, "/runner/.well-known/openid-configuration": { "get": { "description": "Returns this cell's OIDC issuer metadata for runner assertion verification.", "operationId": "runnerIssuerDiscovery", "responses": { "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Error" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryDocument" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } } }, "security": [], "summary": "Runner OIDC discovery metadata", "tags": [ "runner-issuer" ] }, "x-upstream": "activity" }, "/sessions/{share_id}": { "get": { "description": "A publicly shared session's transcript, opened from its share link with no sign-in. The link is the only capability: it resolves to the session server-side and is served from the snapshot captured when it was shared. Revoking the share, or turning the repository's public sharing off, makes the link stop working.", "operationId": "sharedSessionTranscript", "parameters": [ { "in": "path", "name": "share_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTranscriptOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "summary": "A shared session's transcript, by share link", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/sessions/{share_id}/subagents": { "get": { "operationId": "sharedSessionSubagents", "parameters": [ { "in": "path", "name": "share_id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum children to return (default 50, maximum 200)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Maximum children to return (default 50, maximum 200)", "format": "int64", "type": "integer" } }, { "description": "Opaque pagination cursor", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSubagentsOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "summary": "Subagent sessions in a shared session snapshot", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/sessions/{share_id}/subagents/{subagent_id}/transcript": { "get": { "operationId": "sharedSessionSubagentTranscript", "parameters": [ { "in": "path", "name": "share_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "subagent_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSubagentTranscriptOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "summary": "A subagent transcript in a shared session snapshot", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/sessions:resolve-names": { "post": { "description": "The cross-repo batch form of the per-repo sessions:resolve-names: one call resolves session display names (and, with include:[\"rows\"], full list rows) for every repo group on a search page, keyed by the requested repo id. Authorization is per repo — a repo the caller cannot read (including its checkpoint-storage repo when that is separate), that this region does not host, or whose read failed is silently absent from the response, and its ids must be treated as unanswered, not as authoritatively absent. Session ids unknown to a RESOLVED repo are absent from that repo's maps, which IS authoritative. The total session ids across all groups is capped at 500 (one search page). Row items carry the stored ingest-time author login; this read performs no live identity resolve (the search caller renders authors from its own index), so it stays cell-local.", "operationId": "sessionsResolveNamesBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNamesBatchResolveInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionNamesBatchResolveOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Resolve sessions' display names and list rows across repos", "tags": [ "sessions" ] }, "x-upstream": "activity" }, "/trails": { "get": { "description": "Lists Trails in exactly one required projectId. Missing or multiple project scopes are rejected; there is no global discovery or cross-cell merge. Project authority or read access to a repository in the stored scope admits a Trail; empty scopes require project authority. repoId is an optional filter within that project, not an alternative scope, and requires repository read access. Authorization and independently readable Change phases apply before filtering, counts, grouping, and keyset pagination. Each page includes exact totals and a project- and filter-bound nextPageToken.", "operationId": "projectTrailsList", "parameters": [ { "description": "Exactly one project ULID; required addressing scope", "explode": false, "in": "query", "name": "projectId", "required": true, "schema": { "description": "Exactly one project ULID; required addressing scope", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "explode": false, "in": "query", "name": "repoId", "schema": { "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Match any of these statuses (repeatable or comma-separated)", "explode": true, "in": "query", "name": "status", "schema": { "description": "Match any of these statuses (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses (repeatable or comma-separated)", "explode": true, "in": "query", "name": "statusNot", "schema": { "description": "Exclude these statuses (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these priorities (repeatable or comma-separated)", "explode": true, "in": "query", "name": "priority", "schema": { "description": "Match any of these priorities (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these priorities (repeatable or comma-separated)", "explode": true, "in": "query", "name": "priorityNot", "schema": { "description": "Exclude these priorities (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these types (repeatable or comma-separated)", "explode": true, "in": "query", "name": "type", "schema": { "description": "Match any of these types (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these types (repeatable or comma-separated)", "explode": true, "in": "query", "name": "typeNot", "schema": { "description": "Exclude these types (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these author account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "author", "schema": { "description": "Match any of these author account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these author account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "authorNot", "schema": { "description": "Exclude these author account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated); a value that is not a ULID matches nothing", "explode": true, "in": "query", "name": "assignee", "schema": { "description": "Match any of these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated); a value that is not a ULID matches nothing", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated)", "explode": true, "in": "query", "name": "assigneeNot", "schema": { "description": "Exclude these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Case-insensitive search over Trail text; project lists also match #number and project identity", "explode": false, "in": "query", "name": "search", "schema": { "description": "Case-insensitive search over Trail text; project lists also match #number and project identity", "type": "string" } }, { "description": "Match any of these derived phases (repeatable or comma-separated)", "explode": true, "in": "query", "name": "phase", "schema": { "description": "Match any of these derived phases (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these derived phases (repeatable or comma-separated)", "explode": true, "in": "query", "name": "phaseNot", "schema": { "description": "Exclude these derived phases (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "explode": false, "in": "query", "name": "sort", "schema": { "default": "updated", "enum": [ "updated", "title", "status", "type", "priority", "assignee" ], "type": "string" } }, { "explode": false, "in": "query", "name": "groupBy", "schema": { "default": "none", "enum": [ "none", "project", "status", "phase", "author", "assignee" ], "type": "string" } }, { "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTrailsListResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List Trails in one explicitly addressed project", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/trails/facets": { "get": { "description": "Returns requested facets within exactly one required projectId, with the same scoped authorization as GET /trails. Each facet ignores only its own selected values, so the picker remains usable while all other filters continue to constrain its counts.", "operationId": "projectTrailFacets", "parameters": [ { "description": "Exactly one project ULID; required addressing scope", "explode": false, "in": "query", "name": "projectId", "required": true, "schema": { "description": "Exactly one project ULID; required addressing scope", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "explode": false, "in": "query", "name": "repoId", "schema": { "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Match any of these statuses (repeatable or comma-separated)", "explode": true, "in": "query", "name": "status", "schema": { "description": "Match any of these statuses (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses (repeatable or comma-separated)", "explode": true, "in": "query", "name": "statusNot", "schema": { "description": "Exclude these statuses (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these priorities (repeatable or comma-separated)", "explode": true, "in": "query", "name": "priority", "schema": { "description": "Match any of these priorities (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these priorities (repeatable or comma-separated)", "explode": true, "in": "query", "name": "priorityNot", "schema": { "description": "Exclude these priorities (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these types (repeatable or comma-separated)", "explode": true, "in": "query", "name": "type", "schema": { "description": "Match any of these types (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these types (repeatable or comma-separated)", "explode": true, "in": "query", "name": "typeNot", "schema": { "description": "Exclude these types (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these author account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "author", "schema": { "description": "Match any of these author account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these author account ULIDs (repeatable or comma-separated)", "explode": true, "in": "query", "name": "authorNot", "schema": { "description": "Exclude these author account ULIDs (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated); a value that is not a ULID matches nothing", "explode": true, "in": "query", "name": "assignee", "schema": { "description": "Match any of these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated); a value that is not a ULID matches nothing", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated)", "explode": true, "in": "query", "name": "assigneeNot", "schema": { "description": "Exclude these assignee account ULIDs, bare or ulid:-prefixed (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Case-insensitive search over Trail text; project lists also match #number and project identity", "explode": false, "in": "query", "name": "search", "schema": { "description": "Case-insensitive search over Trail text; project lists also match #number and project identity", "type": "string" } }, { "description": "Match any of these derived phases (repeatable or comma-separated)", "explode": true, "in": "query", "name": "phase", "schema": { "description": "Match any of these derived phases (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these derived phases (repeatable or comma-separated)", "explode": true, "in": "query", "name": "phaseNot", "schema": { "description": "Exclude these derived phases (repeatable or comma-separated)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Facets to calculate: author and/or assignee (repeatable or comma-separated); defaults to both", "explode": true, "in": "query", "name": "facet", "schema": { "description": "Facets to calculate: author and/or assignee (repeatable or comma-separated); defaults to both", "items": { "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalProjectTrailFacetsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Calculate facets for one explicitly addressed project", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/trails/repos": { "get": { "description": "Returns repositories owned by exactly one required project_id with Trails enabled whose processing-primary placement is recorded in this cell, including repositories with no Trails yet. Only repositories the caller can read (repo/pull, or an automation's read_trails) are returned; project authority does not bypass repository access. Only the processing-primary placement is returned for each repo group; secondary placements are never used as a fallback. Read-time permission filtering may temporarily omit newly granted repositories; when the readable set is empty, repository denials are rechecked at full consistency before the empty-list or 404 decision. Results contain id, full_name, and forge, ordered by case-insensitive full_name then id, with no pagination. Project viewers/managers receive an empty repositories array when none are readable and enabled; other callers receive 404. Use the project's jurisdiction, as for GET /trails.", "operationId": "projectTrailRepositories", "parameters": [ { "description": "Exactly one project ULID", "explode": false, "in": "query", "name": "project_id", "required": true, "schema": { "description": "Exactly one project ULID", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Required repository permission; project authority never substitutes for it", "explode": false, "in": "query", "name": "permission", "schema": { "default": "read", "description": "Required repository permission; project authority never substitutes for it", "enum": [ "read", "write" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTrailRepositoriesResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List repositories with Trails enabled in one project", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}": { "get": { "description": "The repository's trails, ordered by updated_at descending, then id descending. Cursors restore active filters and ordering; they do not freeze a snapshot. Repeated filters must match the cursor. Callers without access receive 403; authorized callers receive 404 when trails are unavailable.", "operationId": "trailsList", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor; restores filters and ordering. Authorization is checked again on every request.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor; restores filters and ordering. Authorization is checked again on every request.", "type": "string" } }, { "description": "Alias for id[eq]; repository-scoped Trail ULIDs.", "explode": true, "in": "query", "name": "id", "schema": { "description": "Alias for id[eq]; repository-scoped Trail ULIDs.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any Trail ULID; repeatable or comma-separated.", "explode": true, "in": "query", "name": "id[eq]", "schema": { "description": "Match any Trail ULID; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude Trail ULIDs; repeatable or comma-separated.", "explode": true, "in": "query", "name": "id[ne]", "schema": { "description": "Exclude Trail ULIDs; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for status[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status", "schema": { "description": "Alias for status[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any lifecycle status; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[eq]", "schema": { "description": "Match any lifecycle status; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude lifecycle statuses; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[ne]", "schema": { "description": "Exclude lifecycle statuses; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for priority[eq].", "explode": true, "in": "query", "name": "priority", "schema": { "description": "Alias for priority[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any priority; repeatable or comma-separated.", "explode": true, "in": "query", "name": "priority[eq]", "schema": { "description": "Match any priority; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude priorities; repeatable or comma-separated.", "explode": true, "in": "query", "name": "priority[ne]", "schema": { "description": "Exclude priorities; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for type[eq].", "explode": true, "in": "query", "name": "type", "schema": { "description": "Alias for type[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any Trail type; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[eq]", "schema": { "description": "Match any Trail type; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude Trail types; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[ne]", "schema": { "description": "Exclude Trail types; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for author[eq].", "explode": true, "in": "query", "name": "author", "schema": { "description": "Alias for author[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any author account ULID; repeatable or comma-separated.", "explode": true, "in": "query", "name": "author[eq]", "schema": { "description": "Match any author account ULID; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude author account ULIDs; repeatable or comma-separated.", "explode": true, "in": "query", "name": "author[ne]", "schema": { "description": "Exclude author account ULIDs; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for assignee[eq].", "explode": true, "in": "query", "name": "assignee", "schema": { "description": "Alias for assignee[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any assignee account ULID; repeatable or comma-separated.", "explode": true, "in": "query", "name": "assignee[eq]", "schema": { "description": "Match any assignee account ULID; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude assignee account ULIDs; repeatable or comma-separated.", "explode": true, "in": "query", "name": "assignee[ne]", "schema": { "description": "Exclude assignee account ULIDs; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for phase[eq].", "explode": true, "in": "query", "name": "phase", "schema": { "description": "Alias for phase[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any derived phase: planning, building, reviewing; repeatable or comma-separated.", "explode": true, "in": "query", "name": "phase[eq]", "schema": { "description": "Match any derived phase: planning, building, reviewing; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude derived phases: planning, building, reviewing; repeatable or comma-separated.", "explode": true, "in": "query", "name": "phase[ne]", "schema": { "description": "Exclude derived phases: planning, building, reviewing; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for display_status[eq].", "explode": true, "in": "query", "name": "display_status", "schema": { "description": "Alias for display_status[eq].", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match the union of lifecycle statuses (draft, merged, closed) and phases (planning, building, reviewing); repeatable or comma-separated. Planning-or-merged matches either condition.", "explode": true, "in": "query", "name": "display_status[eq]", "schema": { "description": "Match the union of lifecycle statuses (draft, merged, closed) and phases (planning, building, reviewing); repeatable or comma-separated. Planning-or-merged matches either condition.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude the union of lifecycle-status and phase matches: draft, planning, building, reviewing, merged, closed.", "explode": true, "in": "query", "name": "display_status[ne]", "schema": { "description": "Exclude the union of lifecycle-status and phase matches: draft, planning, building, reviewing, merged, closed.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Case-insensitive substring search over title, branch and original_branch.", "explode": false, "in": "query", "name": "q", "schema": { "description": "Case-insensitive substring search over title, branch and original_branch.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailsListResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a repo's trails", "tags": [ "trails" ] }, "post": { "description": "Creates a trail, allocating its per-repository number. Repo-level descriptions are not supported; legacy body fields are ignored. Use the project Trail body instead. status defaults to open and may be open or closed; draft is not supported, and merged is not a creatable status (400) — a trail only becomes merged through the merge endpoint. Asking for a branch that another trail already claims returns that conflict rather than a duplicate. A branch_name is required. The branch must be created successfully or, with branch_action=link, already exist; failed branch preparation never creates an unlinked trail.", "operationId": "trailsCreate", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailCreateRequestJSON" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailCreateResponseBody" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create a trail", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/gates": { "get": { "description": "Returns the repository's gate configuration as gates and gatesEnabled, including disabled gates and each gate's editable configuration. Built-in definitions are initialized when missing, and configuration remains available while repository-wide gate enforcement is disabled.", "operationId": "trailGateConfig", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailGateConfigResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get repository gate configuration", "tags": [ "trail-gates" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}": { "delete": { "deprecated": true, "description": "Deprecated: mark the trail as closed instead (status \"closed\"). Deletes the trail and its discussion, releasing its branch claim; Owned Changes are rejected with 409. Optionally conditional via If-Match.", "operationId": "trailsDelete", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a trail", "tags": [ "trails" ] }, "get": { "description": "A single trail by number: every list-item field plus its body document and monitor results. checkpoints, checkpoint count, and write permission are not included here — the caller composes those from elsewhere.", "operationId": "trailDetail", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDetailResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a trail by number", "tags": [ "trails" ] }, "patch": { "description": "Updates trail metadata. status moves between open and closed (including reopening), but never to draft or merged: merging is executed by the merge endpoint, and asking for status=merged here is refused with 422 and writes nothing — as is any status change on an already-merged trail, whose other metadata stays editable. Repo trail body updates are not supported. Optionally conditional: send If-Match with the trail's ETag and a concurrent change is rejected with 412 instead of silently overwritten.", "operationId": "trailsUpdate", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "in": "header", "name": "If-Match", "schema": { "description": "Optimistic concurrency: a weak ETag (W/\"\u003cupdatedAt\u003e\") from a prior read/write. If present, the request 412s when it no longer matches the trail's current ETag. Omit to apply unconditionally (backward-compatible default).", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailUpdateRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailUpdateResponseBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a trail's metadata", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/approvals": { "get": { "operationId": "trailsApprovals", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailApprovalsResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a trail's recorded approval decisions", "tags": [ "trail-approvals" ] }, "post": { "operationId": "trailsApprovalsSubmit", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailApprovalSubmitRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailApprovalSubmitResponse" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Submit an approval decision on a trail", "tags": [ "trail-approvals" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/body-document/ensure": { "post": { "description": "Ensures the trail's body editor document exists before an editor connects, returning the authoritative document key — imported documents keep their legacy key, so callers must round-trip it rather than reconstruct it. Idempotent: always 201 (never 200, per house convention for creates), and Location is set unconditionally on every response pointing at the document's sync endpoint, whether this call minted the document or one already existed. Deliberately read-gated (repo.pull): anyone who may open the editor may mint the empty row.", "operationId": "trailBodyDocumentEnsure", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailBodyDocumentJSON" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Ensure a trail's body editor document exists", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/ci-pr": { "post": { "description": "Ensures an open GitHub-backed Trail with code changes has a draft pull request, adopting an existing proposal for the branch or creating one as the caller. Concurrent provisioning is claim-protected; every successful response is 201 with the resolved pull request's canonical URL in Location.", "operationId": "trailsCreateCIPr", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailCIPrResponse" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Gateway" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create or link a CI pull request for a Trail", "tags": [ "trails" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/discussions": { "get": { "operationId": "trailDiscussionsList", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Page size, clamped to 1..100", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Page size, clamped to 1..100", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a prior next_cursor", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a prior next_cursor", "type": "string" } }, { "description": "Embed each discussion's messages, as the detail route returns them", "explode": false, "in": "query", "name": "include_messages", "schema": { "description": "Embed each discussion's messages, as the detail route returns them", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionsListResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a trail's discussions", "tags": [ "trail-discussions" ] }, "post": { "operationId": "trailDiscussionsCreate", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionCreateRequestJSON" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionCreateResponseBody" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Start a new discussion", "tags": [ "trail-discussions" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/discussions/{discussion_id}": { "get": { "operationId": "trailDiscussionDetail", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionDetailResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a discussion and its messages", "tags": [ "trail-discussions" ] }, "patch": { "operationId": "trailDiscussionUpdate", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionUpdateRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionUpdateResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a discussion's title/resolved state", "tags": [ "trail-discussions" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/discussions/{discussion_id}/messages": { "post": { "operationId": "trailDiscussionMessageCreate", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageCreateRequestJSON" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageResponseBody" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Add a message to a discussion", "tags": [ "trail-discussions" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/discussions/{discussion_id}/messages/{message_id}": { "delete": { "operationId": "trailDiscussionMessageDelete", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a message", "tags": [ "trail-discussions" ] }, "patch": { "operationId": "trailDiscussionMessageUpdate", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discussion_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "message_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageUpdateRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Edit a message", "tags": [ "trail-discussions" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/events": { "get": { "description": "Returns trail events oldest-first as JSON with per_page and a filter-bound next_cursor, or SSE for Accept: text/event-stream. SSE resumes with Last-Event-ID (after is its fallback). Event names retain periods between domains and use lowercase snake_case within each segment; the documented catalog is open to future names.", "operationId": "trailEvents", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "description": "Alias for type[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type", "schema": { "description": "Alias for type[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match runner, monitor, or finding categories; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[eq]", "schema": { "description": "Match runner, monitor, or finding categories; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude runner, monitor, or finding categories; repeatable or comma-separated.", "explode": true, "in": "query", "name": "type[ne]", "schema": { "description": "Exclude runner, monitor, or finding categories; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Opaque JSON-page continuation. Filters may be omitted or repeated with matching values.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque JSON-page continuation. Filters may be omitted or repeated with matching values.", "type": "string" } }, { "description": "JSON page size: default 200, capped at 1000; zero returns an empty page.", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "JSON page size: default 200, capped at 1000; zero returns an empty page.", "type": "string" } }, { "description": "Numeric resume cursor: for SSE, used when Last-Event-ID is absent; for JSON pages, an alternative first-page start to cursor (mutually exclusive with cursor).", "explode": false, "in": "query", "name": "after", "schema": { "description": "Numeric resume cursor: for SSE, used when Last-Event-ID is absent; for JSON pages, an alternative first-page start to cursor (mutually exclusive with cursor).", "type": "string" } }, { "description": "text/event-stream streams events; otherwise returns a JSON page.", "in": "header", "name": "Accept", "schema": { "description": "text/event-stream streams events; otherwise returns a JSON page.", "type": "string" } }, { "description": "SSE numeric resume cursor; falls back to after.", "in": "header", "name": "Last-Event-ID", "schema": { "description": "SSE numeric resume cursor; falls back to after.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewEventsResponseBody" } }, "text/event-stream": { "schema": { "type": "string" } } }, "description": "JSON event page or SSE stream" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List or stream trail events", "tags": [ "trail-activity" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/reviews": { "post": { "operationId": "reviewStart", "parameters": [ { "description": "Forge host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Forge host slug (gh or et)", "type": "string" } }, { "description": "Repo owner", "in": "path", "name": "owner", "required": true, "schema": { "description": "Repo owner", "type": "string" } }, { "description": "Repo name", "in": "path", "name": "repo", "required": true, "schema": { "description": "Repo name", "type": "string" } }, { "description": "Trail number", "in": "path", "name": "number", "required": true, "schema": { "description": "Trail number", "type": "string" } }, { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewStartRequestJSON" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartReviewResponseBody" } } }, "description": "Created", "headers": { "Idempotency-Replayed": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Start a code review", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/reviews/comments": { "get": { "operationId": "trailReviewCommentsList", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "description": "Alias for status[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status", "schema": { "description": "Alias for status[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "explode": true, "in": "query", "name": "status[eq]", "schema": { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[ne]", "schema": { "description": "Exclude these statuses; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for severity[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "severity", "schema": { "description": "Alias for severity[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of high, medium, low.", "explode": true, "in": "query", "name": "severity[eq]", "schema": { "description": "Match any of high, medium, low.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these severities; comments without a severity remain eligible.", "explode": true, "in": "query", "name": "severity[ne]", "schema": { "description": "Exclude these severities; comments without a severity remain eligible.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "current (default), stale, or any; retained by the cursor.", "explode": false, "in": "query", "name": "stale", "schema": { "description": "current (default), stale, or any; retained by the cursor.", "type": "string" } }, { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "explode": false, "in": "query", "name": "include_dismissed", "schema": { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "type": "string" } }, { "description": "Page size (default 100, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 100, capped at 1000).", "type": "string" } }, { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsPage" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List all review comments for a trail", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/reviews/{review_id}": { "get": { "description": "A review's current state: the review, its pinned code_version, comment counts by status and staleness, and one keyset page of comments each carrying its suggested changes, discussion linkage, and outgoing links. The counts span the whole review regardless of the page filters; the event cursor lets a client resume the trail's event stream at the state the snapshot was read against.", "operationId": "reviewSnapshot", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Include dismissed comments when exactly true; retained by the cursor.", "explode": false, "in": "query", "name": "include_dismissed", "schema": { "description": "Include dismissed comments when exactly true; retained by the cursor.", "type": "string" } }, { "description": "current (default), stale, or any. Unrecognized values mean current; retained by the cursor.", "explode": false, "in": "query", "name": "stale", "schema": { "description": "current (default), stale, or any. Unrecognized values mean current; retained by the cursor.", "type": "string" } }, { "description": "Page size (default 100, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 100, capped at 1000).", "type": "string" } }, { "description": "Opaque continuation cursor; restores filters and ordering. Repeated filters must match.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor; restores filters and ordering. Repeated filters must match.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewSnapshotResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get review state", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/reviews/{review_id}/comments": { "get": { "description": "A review's comments, filtered by status, severity, and staleness. The event cursor returned alongside lets a client resume the trail's event stream at the state the comments were read against.", "operationId": "reviewCommentsList", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Alias for status[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status", "schema": { "description": "Alias for status[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "explode": true, "in": "query", "name": "status[eq]", "schema": { "description": "Match any of open, resolved, dismissed. Overrides the default dismissed exclusion.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these statuses; repeatable or comma-separated.", "explode": true, "in": "query", "name": "status[ne]", "schema": { "description": "Exclude these statuses; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Alias for severity[eq]; repeatable or comma-separated.", "explode": true, "in": "query", "name": "severity", "schema": { "description": "Alias for severity[eq]; repeatable or comma-separated.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Match any of high, medium, low.", "explode": true, "in": "query", "name": "severity[eq]", "schema": { "description": "Match any of high, medium, low.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Exclude these severities; comments without a severity remain eligible.", "explode": true, "in": "query", "name": "severity[ne]", "schema": { "description": "Exclude these severities; comments without a severity remain eligible.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "current (default), stale, or any; retained by the cursor.", "explode": false, "in": "query", "name": "stale", "schema": { "description": "current (default), stale, or any; retained by the cursor.", "type": "string" } }, { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "explode": false, "in": "query", "name": "include_dismissed", "schema": { "description": "Include dismissed comments when exactly true, unless an explicit status filter selects them; retained by the cursor.", "type": "string" } }, { "description": "Page size (default 100, capped at 1000).", "explode": false, "in": "query", "name": "per_page", "schema": { "description": "Page size (default 100, capped at 1000).", "type": "string" } }, { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor. Filters may be omitted or repeated with matching values.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsPage" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List comments for a review", "tags": [ "trail-reviews" ] }, "post": { "operationId": "reviewComments", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional replay-safe key; a retried request with the same key and body returns the cached response instead of re-executing.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentsBatchResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create review comments in a batch", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/trails/{host}/{owner}/{repo}/{number}/reviews/{review_id}/comments/{comment_id}": { "patch": { "operationId": "reviewCommentPatch", "parameters": [ { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "owner", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "number", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "review_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "comment_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentPatchRequestJSON" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCommentJSON" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a review comment", "tags": [ "trail-reviews" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents": { "get": { "description": "Pages the project's agents by id, each at its current version. Archived ones are left out unless include_archived is set. repository_id keeps the agents whose current selection includes that repository. A repository's readers without canManageAgents read its agents' summaries with GET /repos/{repo_id}/agents. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentsList", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor. Restores include_archived and repository_id; repeating either with another value is refused.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor. Restores include_archived and repository_id; repeating either with another value is refused.", "type": "string" } }, { "description": "Also return archived agents. Off by default: the default list answers what can be selected for new use.", "explode": false, "in": "query", "name": "include_archived", "schema": { "description": "Also return archived agents. Off by default: the default list answers what can be selected for new use.", "type": "boolean" } }, { "description": "Only agents whose current selection includes this repository (ULID), including a selected repository the project no longer owns.", "explode": false, "in": "query", "name": "repository_id", "schema": { "description": "Only agents whose current selection includes this repository (ULID), including a selected repository the project no longer owns.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageAgent" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List agents", "tags": [ "agents" ] }, "post": { "description": "Saves a new agent in the project at version 1 and returns it with its JSON etag write token, HTTP ETag and Location. Saving runs nothing. Send preset for an Entire preset, with only the fields that place it (is_enabled, environment, repository_ids, triggers), or every field and a name for a custom agent. Send environment_id or environment: an inline environment is saved in the same transaction as an ordinary, reusable project record, and any refusal saves nothing. Agent names are unique among the project's active agents, ignoring case, and a project runs each preset at most once among its active agents (409 otherwise). It selects repositories of the project and requires repository push on each. Saving starts no run. Idempotency-Key is required: a retry with the same key and body saves nothing and returns the agent the first attempt saved, at its current version, with Idempotency-Replayed: true; the same key with a different body returns 409. A key is scoped to the caller, the project and agents, and does not expire. Bodies use the typed request schema; unknown fields, including spec wrappers and server-owned fields, are refused. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentsCreate", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Required. Reuse it, with the same body, to retry this create: the retry returns the configuration the first attempt saved instead of saving another. The same key with a different body returns 409. Scoped to the caller, project and resource; it does not expire.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Required. Reuse it, with the same body, to retry this create: the retry returns the configuration the first attempt saved instead of saving another. The same key with a different body returns 409. Scoped to the caller, project and resource; it does not expire.", "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Idempotency-Replayed": { "schema": { "description": "true when an earlier create with the same Idempotency-Key saved this configuration and nothing was saved now; absent otherwise.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create an agent", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents/{id}": { "get": { "description": "Returns the agent at its current version, archived or not. Copy its JSON etag value into If-Match for the next replace or archive; compression or intermediaries may transform the HTTP ETag header. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentGet", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get an agent", "tags": [ "agents" ] }, "put": { "description": "Replaces every editable field as a new immutable version; omitted optional fields take their defaults. Send If-Match with the JSON etag value of the last read or write: missing returns 428 and stale returns 412. An archived agent returns 409. Every field, as for a create, with environment_id. A preset agent's name, model, instructions and signal are the preset's: a replace that sends different ones is refused (422); send preset null with every field to customize the agent under the same id. Requires repository push on every repository of the new selection and of the current one the project still owns; a selected repository that has left the project can be dropped without access to it. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentReplace", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "in": "header", "name": "If-Match", "schema": { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReplace" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Required" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Replace an agent", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents/{id}/archive": { "post": { "description": "Archives the agent under the same If-Match precondition as a replace (428 missing, 412 stale). Send no body, or an empty object. The version does not change but the ETag does; history stays readable, the record leaves the default list, and further writes, including a second archive, return 409. Requires repository push on every repository of the current selection the project still owns. Restore it with POST .../agents/{id}/restore. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentArchive", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "in": "header", "name": "If-Match", "schema": { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigArchive" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Required" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Archive an agent", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents/{id}/restore": { "post": { "description": "Makes an archived agent active again under the same id and version; send If-Match with its archived ETag (\"\u003cversion\u003e-archived\"; 428 missing, 412 stale). Send no body, or an empty object. Its name and preset must still be free among the project's active agents (409 otherwise), its environment must still be active (422 otherwise), and restoring an active agent returns 409. Requires repository push on every repository of its selection the project still owns, where it runs again. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentRestore", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "in": "header", "name": "If-Match", "schema": { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigArchive" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Required" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Restore an agent", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents/{id}/runs": { "post": { "description": "Starts one run of the agent on one of a Trail's Changes, in the Change's repository, which the agent must select: it pins the agent's current version (for a preset agent, the preset as it is now), its Environment and the Change's commits into an immutable snapshot, and queues it for the worker. A paused agent still runs when asked to by a caller with canManageAgents. Idempotency-Key is required: an identical repeat returns the first run even after the agent was edited or archived. Project read access admits the caller; anyone else reads the project as not found. A repository's readers act through its own run routes (/repos/{repo_id}/runs). Requires push on the repository (automation principals also project write or manage); without canManageAgents only an enabled agent runs. Served only by the project's primary processing cell.", "operationId": "projectAgentRunsCreate", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "An unarchived agent of the project (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "An unarchived agent of the project (ULID).", "type": "string" } }, { "description": "Required. Repeating the identical request returns the run it first started, even after the agent was edited or archived; a different request under the key is 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Required. Repeating the identical request returns the run it first started, even after the agent was edited or archived; a different request under the key is 409.", "maxLength": 128, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCreate" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "Accepted", "headers": { "Idempotency-Replayed": { "schema": { "description": "true when the Idempotency-Key named an earlier identical request, whose run is returned; omitted otherwise.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Run an agent", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents/{id}/versions": { "get": { "description": "Pages the agent's immutable versions newest first, each with who saved it. History stays readable after archive. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentVersionsList", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageAgentVersion" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List an agent's versions", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/{host}/{project}/agents/{id}/versions/{version}": { "get": { "description": "Returns one immutable version exactly as saved, archived or not. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectAgentVersionGet", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Version number.", "in": "path", "name": "version", "required": true, "schema": { "description": "Version number.", "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersion" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get one version of an agent", "tags": [ "agents" ] }, "x-upstream": "activity" }, "/{host}/{project}/environments": { "get": { "description": "Pages the project's environments by id, each at its current version. Archived ones are left out unless include_archived is set. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentsList", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor. Restores include_archived; repeating include_archived with another value is refused.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor. Restores include_archived; repeating include_archived with another value is refused.", "type": "string" } }, { "description": "Also return archived configurations. Off by default: the default list answers what can be selected for new use.", "explode": false, "in": "query", "name": "include_archived", "schema": { "description": "Also return archived configurations. Off by default: the default list answers what can be selected for new use.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageEnvironment" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List environments", "tags": [ "environments" ] }, "post": { "description": "Saves a new environment in the project at version 1 and returns it with its JSON etag write token, HTTP ETag and Location. Saving runs nothing. It belongs to the project and can be reused across its repositories and agents. Idempotency-Key is required: a retry with the same key and body saves nothing and returns the environment the first attempt saved, at its current version, with Idempotency-Replayed: true; the same key with a different body returns 409. A key is scoped to the caller, the project and environments, and does not expire. Bodies use the typed request schema; unknown fields, including spec wrappers and server-owned fields, are refused. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentsCreate", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Required. Reuse it, with the same body, to retry this create: the retry returns the configuration the first attempt saved instead of saving another. The same key with a different body returns 409. Scoped to the caller, project and resource; it does not expire.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Required. Reuse it, with the same body, to retry this create: the retry returns the configuration the first attempt saved instead of saving another. The same key with a different body returns 409. Scoped to the caller, project and resource; it does not expire.", "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Idempotency-Replayed": { "schema": { "description": "true when an earlier create with the same Idempotency-Key saved this configuration and nothing was saved now; absent otherwise.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create an environment", "tags": [ "environments" ] }, "x-upstream": "activity" }, "/{host}/{project}/environments/{id}": { "get": { "description": "Returns the environment at its current version, archived or not. Copy its JSON etag value into If-Match for the next replace or archive; compression or intermediaries may transform the HTTP ETag header. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentGet", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get an environment", "tags": [ "environments" ] }, "put": { "description": "Replaces every editable field as a new immutable version; omitted optional fields take their defaults. Send If-Match with the JSON etag value of the last read or write: missing returns 428 and stale returns 412. An archived environment returns 409. When unarchived agents — enabled or not — reference the environment, the replace changes what they would run, so it also requires repository push on every repository they select (403 otherwise; 409 if that set changes while the request is being authorized). Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentReplace", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "in": "header", "name": "If-Match", "schema": { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentReplace" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Required" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Replace an environment", "tags": [ "environments" ] }, "x-upstream": "activity" }, "/{host}/{project}/environments/{id}/archive": { "post": { "description": "Archives the environment under the same If-Match precondition as a replace (428 missing, 412 stale). Send no body, or an empty object. The version does not change but the ETag does; history stays readable, the record leaves the default list, and further writes, including a second archive, return 409. Archiving an environment that an unarchived agent references, enabled or not, returns 409. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentArchive", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "in": "header", "name": "If-Match", "schema": { "description": "Required: copy the JSON etag write token from the last read or write of this configuration. Missing returns 428; stale returns 412.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigArchive" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Failed" }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Precondition Required" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Archive an environment", "tags": [ "environments" ] }, "x-upstream": "activity" }, "/{host}/{project}/environments/{id}/versions": { "get": { "description": "Pages the environment's immutable versions newest first, each with who saved it. History stays readable after archive. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentVersionsList", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageEnvironmentVersion" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List an environment's versions", "tags": [ "environments" ] }, "x-upstream": "activity" }, "/{host}/{project}/environments/{id}/versions/{version}": { "get": { "description": "Returns one immutable version exactly as saved, archived or not. Requires canManageAgents (automation principals require project write or manage). Route requests to the project's API URL returned by Core.", "operationId": "projectEnvironmentVersionGet", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Agent or Environment id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Agent or Environment id (ULID).", "type": "string" } }, { "description": "Version number.", "in": "path", "name": "version", "required": true, "schema": { "description": "Version number.", "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentVersion" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get one version of an environment", "tags": [ "environments" ] }, "x-upstream": "activity" }, "/{host}/{project}/runner-status": { "get": { "description": "Whether runs in the project are currently refused, as core's runner admission would decide for the project. Reading it changes nothing, so it is safe to poll. Billing refusals report paused_by billing without the reason; billing_subject is who pays for the project's runs. A stop scoped to one repo group does not pause the project.", "operationId": "projectRunnerStatus", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoRunnerAdmission" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get whether a project's runs are paused", "tags": [ "trail-runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/runs": { "get": { "description": "Pages the project's agent runs newest first, in repositories the caller can pull. Project read access, or pull on any repository the project owns, admits the caller; anyone else reads the project as not found. Requires pull on the run's repository; events and diagnostic are returned only with push on it or canManageAgents, and billing_subject only to project readers. Served only by the project's primary processing cell.", "operationId": "projectRunsList", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Only runs of this agent.", "explode": false, "in": "query", "name": "agent_id", "schema": { "description": "Only runs of this agent.", "type": "string" } }, { "description": "Only runs in this repository (ULID). Without pull on it the page is empty.", "explode": false, "in": "query", "name": "repository_id", "schema": { "description": "Only runs in this repository (ULID). Without pull on it the page is empty.", "type": "string" } }, { "description": "Only runs on a Change of this product Trail.", "explode": false, "in": "query", "name": "trail_id", "schema": { "description": "Only runs on a Change of this product Trail.", "type": "string" } }, { "description": "Only runs on this Change.", "explode": false, "in": "query", "name": "change_id", "schema": { "description": "Only runs on this Change.", "type": "string" } }, { "description": "Only runs in this status.", "explode": false, "in": "query", "name": "status", "schema": { "description": "Only runs in this status.", "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor. Send it with the filters of the page that returned it; other filters are refused (400).", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor. Send it with the filters of the page that returned it; other filters are refused (400).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigPageRunSummary" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List runs", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/runs/{id}": { "get": { "description": "Returns a run's status, the agent, environment, target and runtime it pinned, its provenance, dispatch state, result, captured output, credential-redacted failure diagnostic and events. Events are empty and diagnostic null for a caller without push on the repository or canManageAgents: both are raw process output, redacted only on a best-effort basis. Project read access, or pull on any repository the project owns, admits the caller; anyone else reads the project as not found. Requires pull on the run's repository; events and diagnostic are returned only with push on it or canManageAgents, and billing_subject only to project readers. Served only by the project's primary processing cell.", "operationId": "projectRunGet", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a run", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/runs/{id}/cancel": { "post": { "description": "Cancels a run that has not finished — queued or running — and returns it. Canceling a finished run changes nothing and returns it as it ended. The runner releases any sandbox the run allocated, including one whose provisioning was in flight. Project read access admits the caller; anyone else reads the project as not found. A repository's readers act through its own run routes (/repos/{repo_id}/runs). Requires push on the repository (automation principals also project write or manage), and canManageAgents to cancel a run someone else started or a push started. Served only by the project's primary processing cell.", "operationId": "projectRunCancel", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Cancel a run", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/runs/{id}/retry": { "post": { "description": "Starts the next attempt of a failed, timed-out or canceled run from its snapshot, verbatim — whatever the agent has become since, archived excepted — attributed to the caller. The repository must still be the project's here, the agent must still be unarchived and select it, and the Change must still be the Trail's. Project read access admits the caller; anyone else reads the project as not found. A repository's readers act through its own run routes (/repos/{repo_id}/runs). Requires push on the repository (automation principals also project write or manage); without canManageAgents only an enabled agent runs. Served only by the project's primary processing cell.", "operationId": "projectRunRetry", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } }, { "description": "Optional. Shares the run starts' key space: the same key cannot name both.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional. Shares the run starts' key space: the same key cannot name both.", "maxLength": 128, "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "description": "Accepted", "headers": { "Idempotency-Replayed": { "schema": { "description": "true when the Idempotency-Key named an earlier identical request, whose run is returned; omitted otherwise.", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Conflict" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Retry a run", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/runs/{id}/snapshot": { "get": { "description": "Returns the immutable snapshot the run was admitted with: every pinned spec verbatim, the resolved target, rendered prompt, runtime and provenance. It is never re-derived from current configuration, and holds no credential. For a caller without configuration access it holds what the run records of itself, not the agent's configuration: the pinned agent's repository_ids hold only the run's repository, its instructions and the rendered prompt are left out, and the Environment is its id and version alone. Project read access, or pull on any repository the project owns, admits the caller; anyone else reads the project as not found. Requires pull on the run's repository; events and diagnostic are returned only with push on it or canManageAgents, and billing_subject only to project readers. Served only by the project's primary processing cell.", "operationId": "projectRunSnapshotGet", "parameters": [ { "description": "Project host slug (gh or et).", "in": "path", "name": "host", "required": true, "schema": { "description": "Project host slug (gh or et).", "type": "string" } }, { "description": "Canonical public project name.", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name.", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Run id (ULID).", "in": "path", "name": "id", "required": true, "schema": { "description": "Run id (ULID).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unauthorized" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Forbidden" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Not Found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDocument" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a run's snapshot", "tags": [ "runs" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails": { "post": { "description": "Repo writers need push (an automation: push or write_trails) on every repository in a nonempty project scope. Automations cannot set assignees. Unscoped creation and initial Changes require project management. Initial Changes require Idempotency-Key; database writes are atomic, Git refs are not.", "operationId": "projectTrailsCreate", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Required when changes is non-empty; reuse for retries (24-hour retention)", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required when changes is non-empty; reuse for retries (24-hour retention)", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTrailCreateBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailResponse" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create a project trail", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}": { "get": { "description": "Get a project Trail by ULID or project-local number. With platform_read=true, a successful account read records a last-visited server timestamp on a best-effort basis. Unmarked reads and automation reads do not record visits. Trail timestamps and ETag are unchanged.", "operationId": "projectTrailDetail", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Set by the UI when viewing Trail details to record the caller's last visit; omit for background reads", "explode": false, "in": "query", "name": "platform_read", "schema": { "default": false, "description": "Set by the UI when viewing Trail details to record the caller's last visit; omit for background reads", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailResponse" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a project trail", "tags": [ "projects" ] }, "patch": { "description": "Updates shared intent, metadata, or lifecycle fields for project managers or writers on any repository in the current stored scope. An automation may write with write_trails in place of push, but cannot supply assignees. Only project managers may supply repoIds; proposed scope never authorizes a write. Scope-only writers are fenced against concurrent scope changes even without If-Match. Manager updates remain optionally conditional through If-Match.", "operationId": "projectTrailUpdate", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTrailUpdateBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailResponse" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a project trail", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/changes": { "post": { "description": "Create a new branch-backed Change, or use branchAction=link to reuse existing repository work. Linking preserves existing fields, returns same-parent work unchanged, and rejects another parent. Creation fields are validated but only applied to new work. A legacy body field is ignored; descriptions belong to the project Trail. Trail editors with write access to a repository in the same project may create Changes and add that repository to the scope. Scope removal/replacement remains project-managed.", "operationId": "trailChangeCreate", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Parent Trail ETag", "in": "header", "name": "If-Match", "required": true, "schema": { "description": "Parent Trail ETag", "minLength": 1, "type": "string" } }, { "description": "Reuse for retries of the same creation request (24-hour retention)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "Reuse for retries of the same creation request (24-hour retention)", "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailChangeCreateInputBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailChangeCreateOutputBody" } } }, "description": "Created", "headers": { "ETag": { "schema": { "description": "Updated parent Trail ETag", "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Required" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Create a Change within a Trail", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/changes/{changeId}": { "delete": { "deprecated": true, "description": "Releases the stable Change ID from its project Trail without deleting the backing repository code work. A successful detach advances the Trail version and records the ownership removal in its lifecycle history; denied and unknown Changes remain indistinguishable.", "operationId": "trailChangeDetach", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Stable Change ULID", "in": "path", "name": "changeId", "required": true, "schema": { "description": "Stable Change ULID", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Reject detaching a Change from its required Trail", "tags": [ "projects" ] }, "get": { "description": "Returns repository code work owned by a project Trail under its stable Change ID. Repository access is checked independently; a denied or unknown Change returns the same 404. Repository and branch are display attributes and do not affect the URL.", "operationId": "trailChangeDetail", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Stable Change ULID", "in": "path", "name": "changeId", "required": true, "schema": { "description": "Stable Change ULID", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a Trail's Change by stable ID", "tags": [ "projects" ] }, "put": { "description": "Makes existing repository code work an owned Change under its stable Change ID. The Change's repository must be in the Trail's scope, and the caller needs both project write and repository push access. Attachment is idempotent: a replay for the same Trail returns the same Change and Location with 201.", "operationId": "trailChangeAttach", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Stable Change ULID", "in": "path", "name": "changeId", "required": true, "schema": { "description": "Stable Change ULID", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSummaryResponse" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Attach a Change to a Trail", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/discussions": { "get": { "description": "Lists general discussions owned directly by this project Trail, including empty Trails. Uses the parent's project-view or relevant-repository-pull policy. Returns a resumable event cursor and updated-at/ID pagination; no repository or Change is required.", "operationId": "projectDiscussionsList", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "explode": false, "in": "query", "name": "pageSize", "schema": { "default": 50, "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "explode": false, "in": "query", "name": "pageToken", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscussionsListResponseBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List a project Trail's discussions", "tags": [ "projects" ] }, "post": { "description": "Creates a discussion and its first message under this project Trail. Requires project management or push on a repository in the Trail's current stored scope; does not create repository work, advance the parent metadata ETag, or run code-review automation.", "operationId": "projectDiscussionCreate", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionCreateBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscussionCreateResponseBody" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Start a project Trail discussion", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/discussions/stream": { "get": { "description": "Returns ordered conversation events as JSON, or SSE for Accept: text/event-stream. Resume with after or Last-Event-ID (SSE header takes precedence). Events belong to the project Trail, never a repository; active streams periodically recheck parent access.", "operationId": "projectDiscussionEvents", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "explode": false, "in": "query", "name": "after", "schema": { "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "type": "string" } }, { "in": "header", "name": "Accept", "schema": { "type": "string" } }, { "in": "header", "name": "Last-Event-ID", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscussionEventsResponseBody" } }, "text/event-stream": { "schema": { "type": "string" } } }, "description": "JSON event page or SSE stream" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List or stream project Trail discussion events", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/discussions/{discussionId}": { "get": { "description": "Returns a discussion, its messages, and a resumable event cursor after checking project-Trail access and discussion containment. Unknown, mismatched, and denied resources return 404.", "operationId": "projectDiscussionDetail", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "in": "path", "name": "discussionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscussionDetailResponseBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Read a project Trail discussion", "tags": [ "projects" ] }, "patch": { "description": "Updates a discussion title or resolves/reopens it. Requires project management or stored-scope repository push, and containment under the addressed Trail. Accepts optional If-Match against the discussion's own ETag, returning 412 on mismatch; leaves the parent metadata ETag unchanged.", "operationId": "projectDiscussionUpdate", "parameters": [ { "description": "Optional discussion ETag from a read or write response. Stale or weak validators return 412.", "in": "header", "name": "If-Match", "schema": { "description": "Optional discussion ETag from a read or write response. Stale or weak validators return 412.", "type": "string" } }, { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "in": "path", "name": "discussionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionUpdateBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscussionUpdateResponseBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Update a project Trail discussion", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/discussions/{discussionId}/messages": { "post": { "description": "Replies to a discussion owned by this project Trail. Requires project management or stored-scope repository push, and discussion containment; preserves the shared message response contract.", "operationId": "projectDiscussionMessageCreate", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "in": "path", "name": "discussionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageResponseBody" } } }, "description": "Created", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Reply to a project Trail discussion", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trailId}/discussions/{discussionId}/messages/{messageId}": { "delete": { "description": "Soft-deletes a discussion message and records a message_deleted event. Requires project management or stored-scope repository push, message authorship, and Trail/discussion containment. Optional If-Match uses the message's ETag and returns 412 on mismatch. Returns 204 without changing the parent metadata ETag.", "operationId": "projectDiscussionMessageDelete", "parameters": [ { "description": "Optional message ETag from the message's etag field or write response. Stale or weak validators return 412.", "in": "header", "name": "If-Match", "schema": { "description": "Optional message ETag from the message's etag field or write response. Stale or weak validators return 412.", "type": "string" } }, { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "in": "path", "name": "discussionId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a project Trail discussion message", "tags": [ "projects" ] }, "patch": { "description": "Edits a discussion message. Requires project management or stored-scope repository push, message authorship, and containment under both the addressed Trail and discussion; denied and unknown messages return 404. Optional If-Match uses the message's own ETag; mismatches return 412.", "operationId": "projectDiscussionMessageUpdate", "parameters": [ { "description": "Optional message ETag from the message's etag field or write response. Stale or weak validators return 412.", "in": "header", "name": "If-Match", "schema": { "description": "Optional message ETag from the message's etag field or write response. Stale or weak validators return 412.", "type": "string" } }, { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trailId", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "in": "path", "name": "discussionId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrailDiscussionMessageResponseBody" } } }, "description": "OK", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Edit a project Trail discussion message", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trail_id}/attachments": { "get": { "operationId": "projectTrailAttachmentsList", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "project", "required": true, "schema": { "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAttachmentListOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "List project Trail attachments", "tags": [ "trail-attachments" ] }, "post": { "operationId": "projectTrailAttachmentIntent", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "project", "required": true, "schema": { "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Optional actor-scoped replay key; retries return the original attachment with a fresh upload URL.", "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional actor-scoped replay key; retries return the original attachment with a fresh upload URL.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAttachmentIntentBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAttachmentIntentOutputBody" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Begin a project Trail attachment upload", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trail_id}/attachments/{attachment_id}": { "delete": { "operationId": "projectTrailAttachmentDelete", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "project", "required": true, "schema": { "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Attachment ULID", "in": "path", "name": "attachment_id", "required": true, "schema": { "description": "Attachment ULID", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Delete a project Trail attachment", "tags": [ "trail-attachments" ] }, "get": { "operationId": "projectTrailAttachmentServe", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "project", "required": true, "schema": { "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Attachment ULID", "in": "path", "name": "attachment_id", "required": true, "schema": { "description": "Attachment ULID", "type": "string" } } ], "responses": { "302": { "description": "Found", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Serve a ready project Trail attachment", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trail_id}/attachments/{attachment_id}/complete": { "post": { "operationId": "projectTrailAttachmentComplete", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "project", "required": true, "schema": { "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Attachment ULID", "in": "path", "name": "attachment_id", "required": true, "schema": { "description": "Attachment ULID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAttachmentCompleteOutputBody" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Request Entity Too Large" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Confirm a project Trail attachment upload", "tags": [ "trail-attachments" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trail_id}/body-document/ensure": { "post": { "operationId": "projectTrailBodyDocumentEnsure", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "in": "path", "name": "host", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "project", "required": true, "schema": { "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditorDocumentIdentityJSON" } } }, "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Ensure a project Trail's collaborative body document", "tags": [ "projects" ] }, "x-upstream": "activity" }, "/{host}/{project}/trails/{trail_id}/timeline": { "get": { "description": "Newest-first, cursor-paginated merge of the Trail's creation, lifecycle events (status changes, field updates, Change attach/detach) and discussion comments. Change events are omitted for repositories the caller cannot read.", "operationId": "projectTrailTimeline", "parameters": [ { "description": "Known target project ULID; verified against the canonical project reference", "explode": false, "in": "query", "name": "project_id", "schema": { "description": "Known target project ULID; verified against the canonical project reference", "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, { "description": "Trail host slug (gh or et)", "in": "path", "name": "host", "required": true, "schema": { "description": "Trail host slug (gh or et)", "type": "string" } }, { "description": "Canonical public project name", "in": "path", "name": "project", "required": true, "schema": { "description": "Canonical public project name", "maxLength": 39, "minLength": 1, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$", "type": "string" } }, { "description": "Globally unique Trail ULID or project-local positive number", "in": "path", "name": "trail_id", "required": true, "schema": { "description": "Globally unique Trail ULID or project-local positive number", "pattern": "^([0-7][0-9A-HJKMNP-TV-Z]{25}|[1-9][0-9]{0,9})$", "type": "string" } }, { "description": "Items per page (default 50, maximum 100).", "explode": false, "in": "query", "name": "per_page", "schema": { "default": 50, "description": "Items per page (default 50, maximum 100).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque continuation cursor from next_cursor.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque continuation cursor from next_cursor.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTrailTimelineResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service Unavailable" } }, "security": [ { "oauth2": [] }, { "oidc": [] }, { "bearerAuth": [] } ], "summary": "Get a project Trail's merged event timeline", "tags": [ "projects" ] }, "x-upstream": "activity" } }, "webhooks": { "installation.created": { "post": { "description": "A customer installed the plugin on a project.", "operationId": "pluginWebhookInstallationCreated", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookInstallationDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Installation created", "x-entire-experimental": true, "x-entire-published": true } }, "installation.deleted": { "post": { "description": "The plugin was uninstalled from the project.", "operationId": "pluginWebhookInstallationDeleted", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookInstallationDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Installation deleted", "x-entire-experimental": true, "x-entire-published": true } }, "installation.repositories_added": { "post": { "description": "Repositories were added to the installation.", "operationId": "pluginWebhookInstallationRepositoriesAdded", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookInstallationDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Installation repositories added", "x-entire-experimental": true, "x-entire-published": true } }, "installation.repositories_removed": { "post": { "description": "Repositories were removed from the installation.", "operationId": "pluginWebhookInstallationRepositoriesRemoved", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookInstallationDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Installation repositories removed", "x-entire-experimental": true, "x-entire-published": true } }, "installation.updated": { "post": { "description": "An installation changed.", "operationId": "pluginWebhookInstallationUpdated", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookInstallationDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Installation updated", "x-entire-experimental": true, "x-entire-published": true } }, "ref.created": { "post": { "description": "A branch or tag was created in a repository the installation covers.", "operationId": "pluginWebhookRefCreated", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Ref created", "x-entire-experimental": true, "x-entire-published": true } }, "ref.deleted": { "post": { "description": "A branch or tag was deleted.", "operationId": "pluginWebhookRefDeleted", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Ref deleted", "x-entire-experimental": true, "x-entire-published": true } }, "ref.updated": { "post": { "description": "A branch or tag moved. A force push sets forced to true.", "operationId": "pluginWebhookRefUpdated", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Ref updated", "x-entire-experimental": true, "x-entire-published": true } }, "trail.closed": { "post": { "description": "A trail was closed without a merge.", "operationId": "pluginWebhookTrailClosed", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookTrailDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Trail closed", "x-entire-experimental": true, "x-entire-published": true } }, "trail.merged": { "post": { "description": "A trail was merged into its base.", "operationId": "pluginWebhookTrailMerged", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookTrailDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Trail merged", "x-entire-experimental": true, "x-entire-published": true } }, "trail.opened": { "post": { "description": "A trail was opened, as a draft or ready. Opening a trail does not push a commit, so no ref event may follow.", "operationId": "pluginWebhookTrailOpened", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookTrailDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Trail opened", "x-entire-experimental": true, "x-entire-published": true } }, "trail.reopened": { "post": { "description": "A closed trail was opened again.", "operationId": "pluginWebhookTrailReopened", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookTrailDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Trail reopened", "x-entire-experimental": true, "x-entire-published": true } }, "trail.updated": { "post": { "description": "An open or draft trail changed its head commit, branch, base, title, or draft state. changes names each field that changed.", "operationId": "pluginWebhookTrailUpdated", "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "enum": [ "Entire-Webhooks/1" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginWebhookTrailDelivery" } } }, "required": true }, "responses": { "default": { "description": "Any other status, including a redirect, fails the delivery without a retry. Redirects are not followed." }, "2XX": { "description": "Delivered. Answer within 10 seconds and do the work afterwards." }, "429": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." }, "5XX": { "description": "Retried up to 7 times over about 15 minutes with the same delivery_id, as are network errors and timeouts. Retry-After in seconds can lengthen a wait up to 5 minutes; an HTTP-date Retry-After is ignored." } }, "security": [ { "pluginWebhookToken": [] } ], "summary": "Trail updated", "x-entire-experimental": true, "x-entire-published": true } } }, "components": { "schemas": { "BatchCommitsRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/BatchCommitsRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "includeStats": { "default": false, "description": "Include diff stats (additions, deletions, filesChanged) per commit, from its diff against its first parent. Stats that exceed the per-commit timeout are omitted (null).", "type": "boolean" }, "parseTrailers": { "default": false, "description": "Parse git trailers from each commit message into the trailers field.", "type": "boolean" }, "shas": { "description": "Commit SHAs (full hex) to fetch metadata for. Duplicates and case variants collapse to one entry.", "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "shas" ], "type": "object" }, "BatchObjectsRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/BatchObjectsRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "oids": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "oids" ], "type": "object" }, "BranchMembership": { "additionalProperties": true, "properties": { "onAnyBranch": { "description": "Commit is reachable from any branch (refs/heads/*).", "type": "boolean" }, "onDefaultBranch": { "description": "Commit is reachable from the default branch (HEAD's branch).", "type": "boolean" } }, "required": [ "onDefaultBranch", "onAnyBranch" ], "type": "object" }, "BranchMembershipRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/BranchMembershipRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "targets": { "description": "Commit SHAs (full hex) to classify by branch membership.", "items": { "type": "string" }, "maxItems": 1000, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "targets" ], "type": "object" }, "BranchProtectionResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/BranchProtectionResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "ref": { "type": "string" }, "refProtected": { "type": "boolean" }, "refServerSideMergeOnly": { "type": "boolean" }, "rules": { "items": { "$ref": "#/components/schemas/BranchRule" }, "type": [ "array", "null" ] } }, "required": [ "rules" ], "type": "object" }, "BranchRule": { "additionalProperties": true, "properties": { "ref": { "type": "string" }, "serverSideMergeOnly": { "type": "boolean" } }, "required": [ "ref", "serverSideMergeOnly" ], "type": "object" }, "BranchesContainingRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/BranchesContainingRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "targets": { "description": "Commit SHAs (full hex) to list containing branches for.", "items": { "type": "string" }, "maxItems": 1000, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "targets" ], "type": "object" }, "ChangedFile": { "additionalProperties": true, "properties": { "additions": { "format": "int64", "minimum": 0, "type": "integer" }, "binary": { "type": "boolean" }, "deletions": { "format": "int64", "minimum": 0, "type": "integer" }, "path": { "type": "string" }, "previousPath": { "type": "string" }, "status": { "enum": [ "added", "modified", "removed", "renamed" ], "type": "string" }, "tooLarge": { "type": "boolean" } }, "required": [ "path", "status" ], "type": "object" }, "Commit": { "additionalProperties": true, "properties": { "author": { "$ref": "#/components/schemas/Signature" }, "committer": { "$ref": "#/components/schemas/Signature" }, "extraHeaders": { "items": { "$ref": "#/components/schemas/ExtraHeader" }, "type": [ "array", "null" ] }, "mergeTags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "message": { "type": "string" }, "parents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "sha": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "signature": { "type": "string" }, "stats": { "allOf": [ { "description": "Diff stats vs first parent; present only when includeStats is true. Null if the diff timed out." }, { "$ref": "#/components/schemas/CommitStats" } ] }, "trailers": { "description": "Ordered git trailers; populated only when parseTrailers is true.", "items": { "$ref": "#/components/schemas/Trailer" }, "type": [ "array", "null" ] } }, "required": [ "sha", "parents", "message", "author", "committer" ], "type": "object" }, "CommitAuthor": { "additionalProperties": true, "properties": { "email": { "description": "Author email from the commit header, unnormalized, subject to the standard commit-string sanitization (1024-byte cap, invalid UTF-8 replaced).", "type": "string" }, "name": { "description": "Author name from the first commit seen for this email within the segment.", "type": "string" }, "sampleSha": { "description": "A commit in this segment authored by this email.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "email", "name", "sampleSha" ], "type": "object" }, "CommitFileWrite": { "additionalProperties": true, "properties": { "contentBase64": { "description": "Standard (RFC 4648) base64-encoded file content. Empty creates an empty file.", "type": "string" }, "mode": { "description": "File mode; defaults to 100644.", "enum": [ "100644", "100755" ], "type": "string" }, "path": { "maxLength": 4096, "minLength": 1, "type": "string" } }, "required": [ "path", "contentBase64" ], "type": "object" }, "CommitSignature": { "additionalProperties": true, "properties": { "email": { "maxLength": 320, "minLength": 3, "type": "string" }, "name": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": [ "name", "email" ], "type": "object" }, "CommitStats": { "additionalProperties": true, "properties": { "additions": { "format": "int64", "minimum": 0, "type": "integer" }, "deletions": { "format": "int64", "minimum": 0, "type": "integer" }, "filesChanged": { "format": "int32", "minimum": 0, "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "additions", "deletions", "filesChanged", "truncated" ], "type": "object" }, "CompareResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/CompareResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "files": { "items": { "$ref": "#/components/schemas/ChangedFile" }, "type": [ "array", "null" ] }, "truncated": { "type": "boolean" } }, "required": [ "files", "truncated" ], "type": "object" }, "CompareStatusResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/CompareStatusResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitsAhead": { "description": "Commits reachable from head but not base.", "format": "int32", "minimum": 0, "type": "integer" }, "commitsBehind": { "description": "Commits reachable from base but not head.", "format": "int32", "minimum": 0, "type": "integer" }, "mergeBaseSHA": { "description": "Merge base of base and head; empty for disjoint histories.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "resolvedBaseSHA": { "description": "Commit SHA the base ref resolved to.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "resolvedHeadSHA": { "description": "Commit SHA the head ref resolved to.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "commitsAhead", "commitsBehind", "truncated" ], "type": "object" }, "CreateBranchRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/CreateBranchRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "New branch name, bare (\"feature/x\") or fully qualified (\"refs/heads/feature/x\").", "maxLength": 1024, "minLength": 1, "type": "string" }, "commitSHA": { "description": "Commit the branch points at. The commit must already exist in the repository.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "branch", "commitSHA" ], "type": "object" }, "CreateBranchResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/CreateBranchResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "Fully qualified name of the created branch.", "type": "string" }, "commitSHA": { "description": "Commit the branch was created at.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "branch", "commitSHA" ], "type": "object" }, "CreateCommitRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/CreateCommitRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "author": { "$ref": "#/components/schemas/CommitSignature" }, "expectedOldSHA": { "description": "CAS precondition: the commit SHA the checkpoint ref must currently be at.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "files": { "description": "Files to add or overwrite; deletions are not supported. Decoded file content is limited to 64 MiB total.", "items": { "$ref": "#/components/schemas/CommitFileWrite" }, "maxItems": 1000, "minItems": 1, "type": [ "array", "null" ] }, "message": { "maxLength": 65536, "minLength": 1, "type": "string" }, "ref": { "description": "Existing checkpoint ref: the legacy entire/checkpoints/v1 branch or a ULID ref under refs/entire/checkpoints/.", "minLength": 1, "type": "string" } }, "required": [ "ref", "expectedOldSHA", "message", "author", "files" ], "type": "object" }, "CreateCommitResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/CreateCommitResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "newSHA": { "description": "SHA of the created commit; the checkpoint ref tip after the write.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "newSHA" ], "type": "object" }, "DryRunMergeRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/DryRunMergeRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "baseRef": { "minLength": 1, "type": "string" }, "expectedBaseSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "expectedHeadSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "headRef": { "minLength": 1, "type": "string" }, "strategy": { "enum": [ "merge", "noFastForward", "fastForwardOnly", "squash" ], "type": "string" } }, "required": [ "baseRef", "headRef", "strategy" ], "type": "object" }, "DryRunMergeResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/DryRunMergeResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitsAhead": { "format": "int32", "minimum": 0, "type": "integer" }, "conflictReason": { "enum": [ "treeType", "treeMode", "blobOverlap", "blobBinary" ], "type": "string" }, "conflictedPaths": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "mergeBaseSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "outcome": { "enum": [ "mergeCommit", "fastForward", "squash", "alreadyUpToDate", "conflict" ], "type": "string" }, "resolvedBaseSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "resolvedHeadSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "outcome", "conflictedPaths", "commitsAhead" ], "type": "object" }, "DryRunRebaseRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/DryRunRebaseRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "minLength": 1, "type": "string" }, "onto": { "minLength": 1, "type": "string" }, "upstream": { "type": "string" } }, "required": [ "branch", "onto" ], "type": "object" }, "DryRunRebaseResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/DryRunRebaseResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitsToApply": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "mergeBaseSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "previews": { "items": { "$ref": "#/components/schemas/RebaseCommitPreview" }, "type": [ "array", "null" ] }, "resolvedBranchSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "resolvedOntoSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "wouldSucceed": { "type": "boolean" } }, "required": [ "commitsToApply", "previews", "wouldSucceed" ], "type": "object" }, "DryRunRevertRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/DryRunRevertRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "mainline": { "format": "int32", "minimum": 0, "type": "integer" }, "targetRef": { "minLength": 1, "type": "string" } }, "required": [ "commitSHA", "targetRef" ], "type": "object" }, "DryRunRevertResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/DryRunRevertResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "conflictReason": { "enum": [ "treeType", "treeMode", "blobOverlap", "blobBinary" ], "type": "string" }, "conflictedPaths": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "outcome": { "enum": [ "reverted", "alreadyUpToDate", "conflict" ], "type": "string" }, "resolvedTargetSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "outcome", "conflictedPaths" ], "type": "object" }, "ErrorDetail": { "additionalProperties": true, "properties": { "location": { "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'", "type": "string" }, "message": { "description": "Error message text", "type": "string" }, "value": { "description": "The value at the given location" } }, "type": "object" }, "ErrorModel": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ErrorModel.json" ], "format": "uri", "readOnly": true, "type": "string" }, "detail": { "description": "A human-readable explanation specific to this occurrence of the problem.", "examples": [ "Property foo is required but is missing." ], "type": "string" }, "errors": { "description": "Optional list of individual error details", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": [ "array", "null" ] }, "instance": { "description": "A URI reference that identifies the specific occurrence of the problem.", "examples": [ "https://example.com/error-log/abc123" ], "format": "uri", "type": "string" }, "status": { "description": "HTTP status code", "examples": [ 400 ], "format": "int64", "type": "integer" }, "title": { "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.", "examples": [ "Bad Request" ], "type": "string" }, "type": { "default": "about:blank", "description": "A URI reference to human-readable documentation for the error.", "examples": [ "https://example.com/errors/example" ], "format": "uri", "type": "string" } }, "type": "object" }, "ExtraHeader": { "additionalProperties": true, "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" }, "GetTreeResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/GetTreeResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "entries": { "items": { "$ref": "#/components/schemas/TreeEntry" }, "type": [ "array", "null" ] }, "sha": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "sha", "entries", "truncated" ], "type": "object" }, "LastChangedCommitsRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/LastChangedCommitsRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "parseTrailers": { "default": false, "description": "Parse git trailers from each returned commit message into the trailers field.", "type": "boolean" }, "paths": { "description": "Slash-separated tree paths — a file or a directory — to resolve. Exact duplicates collapse. Paths are taken verbatim: a non-canonical path is rejected rather than rewritten, so every response key is byte-identical to what was asked for.", "items": { "maxLength": 4096, "minLength": 1, "type": "string" }, "maxItems": 200, "minItems": 1, "type": [ "array", "null" ] }, "ref": { "description": "Branch, tag, or commit SHA, optionally with a ^/~N revision suffix (e.g. main~2, \u003csha\u003e^). Every verdict is relative to the commit this resolves to.", "minLength": 1, "type": "string" } }, "required": [ "ref", "paths" ], "type": "object" }, "LastChangedCommitsResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/LastChangedCommitsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commits": { "additionalProperties": { "$ref": "#/components/schemas/Commit" }, "description": "Each distinct commit named by an ok verdict, keyed by canonical SHA.", "type": "object" }, "paths": { "additionalProperties": { "$ref": "#/components/schemas/PathCommit" }, "description": "Verdict per requested path. Every requested path is present.", "type": "object" }, "resolvedRefSHA": { "description": "Commit SHA the ref resolved to; the pin every verdict is relative to.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "resolvedRefSHA", "paths", "commits" ], "type": "object" }, "ListAuthorsRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ListAuthorsRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "pageSize": { "description": "Commit-scan budget for this request segment: the walk consumes up to this many commits before returning, regardless of how many distinct authors it found (default 10000, max 25000). It does not bound the number of authors returned.", "format": "int32", "maximum": 25000, "minimum": 0, "type": "integer" }, "pageToken": { "description": "Opaque continuation token from a prior response's nextPageToken. Carried in the request body, not the query string: it encodes the walk frontier, which on a wide-ref history can exceed URL/request-line limits.", "type": "string" } }, "type": "object" }, "ListAuthorsResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ListAuthorsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "authors": { "items": { "$ref": "#/components/schemas/CommitAuthor" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "authors" ], "type": "object" }, "ListBranchesResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ListBranchesResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "items": { "$ref": "#/components/schemas/Ref" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "branches" ], "type": "object" }, "ListCommitsResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ListCommitsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commits": { "items": { "$ref": "#/components/schemas/Commit" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "commits" ], "type": "object" }, "ListRefsResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ListRefsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "nextPageToken": { "type": "string" }, "refs": { "items": { "$ref": "#/components/schemas/RefEntry" }, "type": [ "array", "null" ] } }, "required": [ "refs" ], "type": "object" }, "ListTagsResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ListTagsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "nextPageToken": { "type": "string" }, "tags": { "items": { "$ref": "#/components/schemas/Ref" }, "type": [ "array", "null" ] } }, "required": [ "tags" ], "type": "object" }, "MergeBaseResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/MergeBaseResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "mergeBaseSHA": { "description": "Commit SHA of the merge base.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "resolvedSHAs": { "description": "Resolved input ref SHAs in request order.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "resolvedSHAs" ], "type": "object" }, "MergeRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/MergeRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "baseRef": { "minLength": 1, "type": "string" }, "commitMessage": { "type": "string" }, "expectedBaseSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "expectedHeadSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "headRef": { "minLength": 1, "type": "string" }, "strategy": { "enum": [ "merge", "noFastForward", "fastForwardOnly", "squash" ], "type": "string" } }, "required": [ "baseRef", "headRef", "strategy", "expectedBaseSHA" ], "type": "object" }, "MergeResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/MergeResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "conflictReason": { "enum": [ "treeType", "treeMode", "blobOverlap", "blobBinary" ], "type": "string" }, "conflictedPaths": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "mergeCommitSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "newBaseSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "outcome": { "enum": [ "mergeCommit", "fastForward", "squash", "alreadyUpToDate", "conflict" ], "type": "string" } }, "required": [ "outcome", "conflictedPaths" ], "type": "object" }, "PathCommit": { "additionalProperties": true, "properties": { "sha": { "description": "Commit that last changed this path, and a key of the commits map. Set only when status is ok.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "status": { "description": "ok: SHA names the commit that last changed this path. notFound: the path is absent at the resolved ref. unresolved: the walk stopped before reaching an answer.", "enum": [ "ok", "notFound", "unresolved" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "RebaseCommitPreview": { "additionalProperties": true, "properties": { "conflictReason": { "enum": [ "treeType", "treeMode", "blobOverlap", "blobBinary" ], "type": "string" }, "conflictedPaths": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "originalSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "wouldBeDropped": { "type": "boolean" }, "wouldConflict": { "type": "boolean" } }, "required": [ "originalSHA", "wouldConflict", "conflictedPaths", "wouldBeDropped" ], "type": "object" }, "RebaseRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/RebaseRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "minLength": 1, "type": "string" }, "expectedBranchSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "expectedOntoSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "onto": { "minLength": 1, "type": "string" }, "upstream": { "type": "string" } }, "required": [ "branch", "onto" ], "type": "object" }, "Ref": { "additionalProperties": true, "properties": { "commitSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "commitSHA" ], "type": "object" }, "RefEntry": { "additionalProperties": true, "properties": { "name": { "description": "Fully-qualified ref name (e.g. \"HEAD\", \"refs/heads/main\", \"refs/tags/v1\").", "type": "string" }, "oid": { "description": "Object the ref points at: a commit for a branch, the tag object for an annotated tag, or HEAD's resolved tip. Omitted for an unborn HEAD.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "peeled": { "description": "The first non-tag object an annotated tag dereferences to (usually a commit). Present only when peel=true and the ref is an annotated tag.", "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "symrefTarget": { "description": "Fully-qualified target of a symbolic ref (e.g. HEAD -\u003e refs/heads/main). Present only when symrefs=true.", "type": "string" }, "unborn": { "description": "True for a HEAD whose symref target has no commit yet (oid omitted). Only emitted when unborn=true.", "type": "boolean" } }, "required": [ "name" ], "type": "object" }, "ResolveResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/ResolveResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "replicas": { "description": "Hosting-node base URIs for the repository.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "repoId": { "description": "Repository ULID.", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$", "type": "string" } }, "required": [ "repoId", "replicas" ], "type": "object" }, "RevertRequest": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/RevertRequest.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "expectedTargetSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "mainline": { "format": "int32", "minimum": 0, "type": "integer" }, "targetRef": { "minLength": 1, "type": "string" } }, "required": [ "commitSHA", "targetRef" ], "type": "object" }, "RevertResponse": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "https://aws-us-east-2.entire.io/api/v1/schemas/RevertResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "conflictReason": { "enum": [ "treeType", "treeMode", "blobOverlap", "blobBinary" ], "type": "string" }, "conflictedPaths": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "newTipSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "outcome": { "enum": [ "reverted", "alreadyUpToDate", "conflict" ], "type": "string" }, "revertCommitSHA": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" } }, "required": [ "outcome", "conflictedPaths" ], "type": "object" }, "Signature": { "additionalProperties": true, "properties": { "date": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "email", "date" ], "type": "object" }, "Trailer": { "additionalProperties": true, "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" }, "TreeEntry": { "additionalProperties": true, "properties": { "mode": { "type": "string" }, "path": { "type": "string" }, "sha": { "pattern": "^[0-9a-f]{40}$|^[0-9a-f]{64}$", "type": "string" }, "size": { "format": "int64", "minimum": 0, "type": "integer" }, "type": { "enum": [ "blob", "tree", "commit" ], "type": "string" } }, "required": [ "path", "mode", "type", "sha", "size" ], "type": "object" }, "SearchResponse": { "type": "object", "required": [ "query", "stats", "repo_stats", "results" ], "properties": { "query": { "type": "string" }, "stats": { "$ref": "#/components/schemas/SearchStats" }, "repo_stats": { "type": "array", "items": { "$ref": "#/components/schemas/RepoStat" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHit" } } } }, "SearchStats": { "type": "object", "required": [ "total_matches", "total_files", "duration_ms", "repos_searched" ], "properties": { "total_matches": { "type": "integer" }, "total_files": { "type": "integer" }, "duration_ms": { "type": "integer" }, "repos_searched": { "type": "integer" }, "repos_failed": { "type": "integer", "description": "Number of repos that failed to search (omitted when 0)" } } }, "RepoStat": { "type": "object", "required": [ "repo", "match_count", "file_count" ], "properties": { "repo": { "type": "string" }, "match_count": { "type": "integer" }, "file_count": { "type": "integer" } } }, "SearchHit": { "type": "object", "required": [ "repo", "path", "line", "column", "context_before", "context_line", "context_after", "score" ], "properties": { "repo": { "type": "string" }, "path": { "type": "string" }, "line": { "type": "integer" }, "column": { "type": "integer" }, "context_before": { "type": "array", "items": { "type": "string" } }, "context_line": { "type": "string" }, "context_after": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number", "format": "double" } } }, "FuzzyResponse": { "type": "object", "required": [ "query", "results", "duration_ms" ], "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FuzzyHit" } }, "duration_ms": { "type": "integer" } } }, "FuzzyHit": { "type": "object", "required": [ "repo", "path" ], "properties": { "repo": { "type": "string" }, "path": { "type": "string" }, "symbol": { "type": "string" }, "kind": { "type": "string" }, "line": { "type": "integer" } } }, "ReposResponse": { "type": "object", "required": [ "repos" ], "properties": { "repos": { "type": "array", "items": { "$ref": "#/components/schemas/RepoEntry" } } } }, "RepoEntry": { "type": "object", "required": [ "name", "repo_id", "org_id", "file_count", "index_size_bytes", "indexed_commit", "indexed_at" ], "properties": { "name": { "type": "string" }, "repo_id": { "type": "string" }, "org_id": { "type": "string" }, "file_count": { "type": "integer" }, "index_size_bytes": { "type": "integer", "format": "int64" }, "indexed_commit": { "type": "string" }, "indexed_at": { "type": "integer", "format": "int64" } } }, "FileResponse": { "type": "object", "required": [ "repo", "path", "content", "language", "total_lines" ], "properties": { "repo": { "type": "string" }, "path": { "type": "string" }, "content": { "type": "string" }, "language": { "type": "string" }, "total_lines": { "type": "integer" }, "symbols": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolEntry" }, "description": "Symbols in the file (only present when ?symbols=true)" } } }, "SymbolsResponse": { "type": "object", "required": [ "symbols" ], "properties": { "symbols": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolEntry" } } } }, "SymbolEntry": { "type": "object", "required": [ "name", "kind", "role", "line", "col_start", "col_end" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "role": { "type": "string" }, "line": { "type": "integer" }, "col_start": { "type": "integer" }, "col_end": { "type": "integer" }, "parent": { "type": "string" }, "signature": { "type": "string" }, "usages_count": { "type": "integer", "description": "Number of known usages; only present on definitions." }, "resolved_to": { "$ref": "#/components/schemas/ResolvedTo" } } }, "ResolvedTo": { "type": "object", "description": "Definition site a reference resolves to (index-time resolution).", "required": [ "path", "line" ], "properties": { "path": { "type": "string" }, "line": { "type": "integer" } } }, "ResolveRequest": { "type": "object", "required": [ "repo", "path" ], "properties": { "repo": { "type": "string" }, "path": { "type": "string" } } }, "ResolveResult": { "type": "object", "required": [ "resolved", "external" ], "properties": { "resolved": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedRef" } }, "external": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalRef" } } } }, "ResolvedRef": { "type": "object", "required": [ "line", "col_start", "col_end", "name", "target_path", "target_line", "kind" ], "properties": { "line": { "type": "integer" }, "col_start": { "type": "integer" }, "col_end": { "type": "integer" }, "name": { "type": "string" }, "target_path": { "type": "string" }, "target_line": { "type": "integer" }, "kind": { "type": "string" } } }, "ExternalRef": { "type": "object", "required": [ "line", "col_start", "col_end", "name", "qualified" ], "properties": { "line": { "type": "integer" }, "col_start": { "type": "integer" }, "col_end": { "type": "integer" }, "name": { "type": "string" }, "qualified": { "type": "string" } } }, "BlameResponse": { "type": "object", "required": [ "runs", "truncated" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/BlameRun" } }, "truncated": { "type": "boolean", "description": "True when the response was cut short by either limit: more overlapping runs than `max`, or the response byte budget was reached." } } }, "BlameRun": { "type": "object", "required": [ "start_line", "end_line", "sha", "author", "timestamp", "checkpoint_ids" ], "properties": { "start_line": { "type": "integer" }, "end_line": { "type": "integer" }, "sha": { "type": "string", "description": "40-character hex commit SHA" }, "author": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64" }, "checkpoint_ids": { "type": "array", "items": { "type": "string" } } } }, "HoverResponse": { "type": "object", "required": [ "name", "kind", "signature", "path", "line" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "signature": { "type": "string", "description": "Full declaration header sliced from source." }, "docs": { "type": "string", "description": "Leading doc comment (markers stripped) or Python docstring." }, "path": { "type": "string" }, "line": { "type": "integer" } } }, "UsagesResponse": { "type": "object", "required": [ "definition", "usages", "total_count", "truncated" ], "properties": { "definition": { "$ref": "#/components/schemas/UsageDefinition" }, "usages": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEntry" } }, "total_count": { "type": "integer" }, "truncated": { "type": "boolean" } } }, "UsageDefinition": { "type": "object", "required": [ "path", "line", "name" ], "properties": { "path": { "type": "string" }, "line": { "type": "integer" }, "name": { "type": "string" } } }, "UsageEntry": { "type": "object", "required": [ "path", "line", "col_start", "col_end", "context" ], "properties": { "path": { "type": "string" }, "line": { "type": "integer" }, "col_start": { "type": "integer" }, "col_end": { "type": "integer" }, "context": { "type": "string", "description": "Trimmed source text of the usage line (capped at 300 chars)" } } }, "TrailMetricsPage": { "type": "object", "required": [ "trail_metrics" ], "properties": { "trail_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/TrailMetrics" } }, "next_cursor": { "type": "string", "description": "Pass as cursor to get the next page. Absent on the last page." } } }, "TrailMetrics": { "type": "object", "required": [ "repo_id", "number", "merged_at", "provisional", "sessions", "models" ], "properties": { "repo_id": { "type": "string" }, "number": { "type": "integer", "format": "int64", "description": "The trail's number in its repo." }, "merged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339, UTC for stored merged metrics; null for provisional open Trail metrics; the merge time for provisional merged-not-yet-computed Trail metrics." }, "provisional": { "type": "boolean" }, "size": { "$ref": "#/components/schemas/ChangeSize" }, "sessions": { "type": "integer", "format": "int32", "description": "Agent sessions in the trail." }, "models": { "type": "array", "description": "Per agent and model, ordered by agent then model. Empty when the trail has no agent work.", "items": { "$ref": "#/components/schemas/ModelUse" } }, "phases": { "type": "array", "description": "Tokens per phase of the trail's agent work, by raw phase name, ordered by phase. Absent when a merged trail has no phase data; always present (possibly empty) for provisional (open or merged-not-yet-computed) Trails. Not split by model.", "items": { "$ref": "#/components/schemas/PhaseUse" } }, "runners": { "type": "array", "description": "Review and monitor usage of the Trail's runner runs and agent runs, one entry per runner (an agent run's agent name) and model, ordered by runner then model; not included in models or phases. Distinct run IDs count once; duplicate model rows within a run are summed. Missing usage retains a zero-counter empty-model sentinel, not measured zero. Always present for provisional responses; consult runner_usage for availability. For stored merged metrics, empty means recorded with no runs and runners are absent while they have not been recorded yet; no new completeness guarantee is inferred.", "items": { "$ref": "#/components/schemas/RunnerUse" } }, "runner_usage": { "$ref": "#/components/schemas/RunnerUsage" }, "notes": { "type": "array", "description": "Computation caveats for provisional (open or merged-not-yet-computed) Trail metrics, including malformed transcript lines skipped, counted once per session from its latest chosen checkpoint snapshot. Absent for stored merged metrics.", "items": { "type": "string" } } } }, "ChangeSize": { "type": "object", "description": "Absent when the trail has no size yet, or cannot be sized (no commit range, or EntireDB lacks one of its commits).", "required": [ "bucket", "additions", "deletions", "files_changed", "truncated" ], "properties": { "bucket": { "type": "string", "description": "Size class over additions plus deletions; one of S, M, L, XL today." }, "additions": { "type": "integer", "format": "int64" }, "deletions": { "type": "integer", "format": "int64" }, "files_changed": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean", "description": "True when the comparison was capped, so the counts are a lower bound." } } }, "TokenCounts": { "type": "object", "required": [ "fresh_input", "cache_read", "cache_write_5m", "cache_write_1h", "output" ], "properties": { "fresh_input": { "type": "integer", "format": "int64", "description": "Input tokens not served from cache." }, "cache_read": { "type": "integer", "format": "int64", "description": "Input served from the prompt cache." }, "cache_write_5m": { "type": "integer", "format": "int64", "description": "Tokens written to the 5-minute cache." }, "cache_write_1h": { "type": "integer", "format": "int64", "description": "Tokens written to the 1-hour cache." }, "output": { "type": "integer", "format": "int64", "description": "Output tokens." } } }, "ModelUse": { "type": "object", "required": [ "agent", "model", "calls", "tokens" ], "properties": { "agent": { "type": "string" }, "model": { "type": "string" }, "calls": { "type": "integer", "format": "int32" }, "tokens": { "$ref": "#/components/schemas/TokenCounts" } } }, "TrailActivitySummary": { "type": "object", "required": [ "trails_with_phases", "phases" ], "properties": { "trails_with_phases": { "type": "integer", "format": "int64", "description": "Distinct Trails with at least one phase row, not the number of phases or all merged Trails." }, "phases": { "type": "array", "description": "Totals by raw phase name, sorted by name; always an array, empty when no phase rows match.", "items": { "$ref": "#/components/schemas/PhaseUse" } }, "development": { "allOf": [ { "description": "Development tokens, the sum of all five counters over every phase row in scope, review_fix included and runner tokens never counted; equals the sum of phases[] tokens, 0 when no phase rows match." }, { "$ref": "#/components/schemas/TokenTotal" } ] }, "review": { "allOf": [ { "description": "Review tokens, the sum of fresh_input, output, cache_write and cache_read over every runner run of Trails in scope (latest TCO row, active installation, same repo and merged_at window), all runners included. Runs are reached through each Trail's TCO row, so a merged Trail whose TCO is unavailable or not yet computed contributes nothing, as in trail-metrics. 0 when none match; runner spend not recorded yet and no runs both read as 0." }, { "$ref": "#/components/schemas/TokenTotal" } ] } } }, "TokenTotal": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "integer", "format": "int64", "description": "Token count summed over the counters named by the field that holds this object." } } }, "PhaseUse": { "type": "object", "required": [ "phase", "tokens" ], "properties": { "phase": { "type": "string", "description": "Raw phase name; new names may appear." }, "tokens": { "$ref": "#/components/schemas/TokenCounts" } } }, "RunnerTokens": { "type": "object", "required": [ "fresh_input", "output", "cache_write", "cache_read" ], "properties": { "fresh_input": { "type": "integer", "format": "int64", "description": "Input tokens not served from cache." }, "output": { "type": "integer", "format": "int64", "description": "Output tokens." }, "cache_write": { "type": "integer", "format": "int64", "description": "Tokens written to the cache" }, "cache_read": { "type": "integer", "format": "int64", "description": "Input served from the prompt cache." } } }, "RunnerUsage": { "type": "object", "description": "Present only and always on provisional single-Trail metrics; absent on stored merged metrics. Describes recorded usage availability, not whether an open Trail can gain future runs.", "required": [ "status", "run_created_at_lte" ], "properties": { "status": { "type": "string", "enum": [ "complete", "partial" ], "description": "Complete requires full enumeration of the Trail's runner runs and agent runs and every eligible run terminal (succeeded, failed, timeout, which includes an agent run's timed_out, or canceled) with nonempty explicit usage records. Partial also means entire-api could not list the Trail's agent runs by Change, so all of its agent runs are left out. Explicit all-zero records count as reported zero; no eligible runs is complete with empty runners. Partial means some eligible run is nonterminal or has absent, null or empty usageByModel, even if terminal. All reported counters remain included; partial with zero known tokens is not measured zero." }, "run_created_at_lte": { "type": "string", "format": "date-time", "description": "UTC RFC 3339 inclusive run creation eligibility bound, not a usage-as-of snapshot. Usage counters reflect when each page was fetched." } } }, "RunnerUse": { "type": "object", "required": [ "runner", "runs", "model", "tokens" ], "properties": { "runner": { "type": "string", "description": "Runner name, or the agent's name for an agent run; empty when the run reported none." }, "runs": { "type": "integer", "format": "int32", "description": "Distinct runs of this runner on this model." }, "model": { "type": "string", "description": "Empty when the run reported no usage or it is not attributable to a model." }, "tokens": { "$ref": "#/components/schemas/RunnerTokens" } } }, "RepoStatus": { "type": "object", "required": [ "repo_id", "installed", "state", "unprocessed_trails", "failed_trails" ], "properties": { "repo_id": { "type": "string" }, "installed": { "type": "boolean", "description": "An active Agent Insights installation of the project covers the repo. False exactly when trail-metrics answers plugin-not-installed for this repo_id." }, "state": { "type": "string", "description": "The repo's processing progress, first match wins: not_installed\n(installed is false); partial (some trail has agent data, model or\nphase usage, and unprocessed_trails is above 0); up_to_date (some trail\nhas agent data and unprocessed_trails is 0); unavailable (processing\ncannot make progress: trail reads are denied, another deployment\nprocesses the repo, intake has not completed a first read within an\nhour, nothing is pending and every change job failed or was\nunavailable, or a checkpoint job failed); not_started (intake has not\ncompleted a first read of the repo); backfilling (read, no agent data\nyet, work pending); none_available (read, nothing pending, and no\nmerged trail carries agent data). New values may appear: a client that\ndoes not know a value should show no status at all, never treat it as\nhealthy.\n" }, "unprocessed_trails": { "type": "integer", "format": "int64", "description": "Merged trails found for the repo that have no metrics at the running version and have not failed. Includes trails waiting to be reprocessed after an upgrade, which an operator's regenerate requeues." }, "failed_trails": { "type": "integer", "format": "int64", "description": "Merged trails found for the repo that have no metrics and never will; their processing failed permanently." }, "last_processed_at": { "type": "string", "format": "date-time", "description": "When the repo's newest trail metrics were written, RFC 3339 UTC. Rewritten by a reprocess, so it reads \"last updated\", not \"last merged\". Absent when the repo has none." } } }, "TrailStats": { "type": "object", "required": [ "trails", "with_cache_reads", "without_cache_reads" ], "properties": { "trails": { "type": "integer", "format": "int64", "description": "The number of peers." }, "with_cache_reads": { "$ref": "#/components/schemas/TokenStats" }, "without_cache_reads": { "$ref": "#/components/schemas/TokenStats" } } }, "TokenStats": { "type": "object", "description": "Token statistics are whole numbers, each null when it cannot be computed. The phase_share properties are present exactly when phase is given.", "required": [ "tokens_median", "tokens_p90", "tokens_per_line_median", "trail_percentile" ], "properties": { "tokens_median": { "type": [ "integer", "null" ], "format": "int64", "description": "Median tokens per peer. Null when there are no peers." }, "tokens_p90": { "type": [ "integer", "null" ], "format": "int64", "description": "90th percentile of tokens per peer. Null when there are no peers." }, "tokens_per_line_median": { "type": [ "integer", "null" ], "format": "int64", "description": "Median of each peer's tokens divided by its additions plus deletions; peers with no changed lines or a truncated comparison are left out. Null when none qualify." }, "trail_percentile": { "type": [ "integer", "null" ], "maximum": 100, "minimum": 0, "format": "int64", "description": "Share of peers with strictly fewer tokens than the trail given in trail" }, "phase_share_median": { "type": [ "number", "null" ], "maximum": 1, "minimum": 0, "format": "double", "description": "Median, over peers, of the phase set's tokens divided by all of the peer's phase tokens (a fraction, as entire.io's activity shares; in this variant both leave out cache reads). Peers with no phase tokens, such as ones computed before phases were stored, are left out. Null when none qualify." }, "phase_share_p90": { "type": [ "number", "null" ], "maximum": 1, "minimum": 0, "format": "double", "description": "90th percentile of the same shares. Null when none qualify." }, "trail_phase_share": { "type": [ "number", "null" ], "maximum": 1, "minimum": 0, "format": "double", "description": "The same share for the trail given in trail. Null when trail is absent" } } }, "TrailBreakdown": { "type": "object", "required": [ "repo_id", "number", "provisional", "merged_at", "notes", "nodes" ], "properties": { "repo_id": { "type": "string" }, "number": { "type": "integer", "format": "int64" }, "provisional": { "type": "boolean" }, "merged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339, UTC; null for an open Trail." }, "notes": { "type": "array", "description": "Computation caveats, as the notes of the same Trail's metrics.", "items": { "type": "string" } }, "nodes": { "type": "array", "description": "Top-level nodes ordered by first_call_at, then id. Empty when the trail has no agent work.", "items": { "$ref": "#/components/schemas/BreakdownNode" } } } }, "BreakdownNode": { "type": "object", "required": [ "kind", "id", "agent", "basis", "calls", "first_call_at", "last_call_at", "tokens", "models", "children" ], "properties": { "kind": { "type": "string", "description": "The node's kind; session in v1." }, "id": { "type": "string", "description": "Unique among its siblings; for a session, the agent's session ID." }, "agent": { "type": "string" }, "basis": { "type": "string", "description": "exact or estimated." }, "calls": { "type": "integer", "format": "int32" }, "first_call_at": { "type": "string", "format": "date-time" }, "last_call_at": { "type": "string", "format": "date-time" }, "tokens": { "$ref": "#/components/schemas/TokenCounts" }, "models": { "type": "array", "description": "The node's totals split by model, ordered by model.", "items": { "$ref": "#/components/schemas/BreakdownModel" } }, "children": { "type": "array", "description": "Child nodes, each shaped like BreakdownNode; empty in v1.", "items": { "type": "object" } } } }, "BreakdownModel": { "type": "object", "required": [ "model", "calls", "tokens" ], "properties": { "model": { "type": "string" }, "calls": { "type": "integer", "format": "int32" }, "tokens": { "$ref": "#/components/schemas/TokenCounts" } } }, "TrailTurns": { "type": "object", "required": [ "repo_id", "number", "provisional", "merged_at", "notes", "turns", "totals" ], "properties": { "repo_id": { "type": "string" }, "number": { "type": "integer", "format": "int64" }, "provisional": { "type": "boolean" }, "merged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339, UTC; null for an open Trail." }, "notes": { "type": "array", "description": "Computation caveats, as the notes of the same Trail's metrics.", "items": { "type": "string" } }, "turns": { "type": "array", "description": "At most limit turns, highest tokens first, then by call time, session ID and call ID. Empty when no call has a share in the phase set.", "items": { "$ref": "#/components/schemas/Turn" } }, "totals": { "$ref": "#/components/schemas/TurnTotals" } } }, "Turn": { "type": "object", "required": [ "session_id", "turn_index", "call_id", "agent", "model", "tokens" ], "properties": { "session_id": { "type": "string", "description": "The agent's session ID; a Claude Code call replayed by resumed or forked sessions belongs to the lowest session ID." }, "turn_index": { "type": "integer", "format": "int32", "description": "Human prompts before this call in its session; 0 before the first." }, "call_id": { "type": "string", "description": "The call's ID within the session" }, "agent": { "type": "string" }, "model": { "type": "string" }, "tokens": { "allOf": [ { "description": "The call's tokens weighted by the summed weight of its phases in the set, rounded per counter." }, { "$ref": "#/components/schemas/TokenCounts" } ] } } }, "TurnTotals": { "type": "object", "required": [ "turns", "tokens" ], "properties": { "turns": { "type": "integer", "format": "int64", "description": "Every turn with a share in the phase set" }, "tokens": { "allOf": [ { "description": "The sum of the set's per-phase totals as the metrics operation rounds them; equals the sum of the same Trail's phases entries for the set." }, { "$ref": "#/components/schemas/TokenCounts" } ] } } }, "Problem": { "type": "object", "description": "An RFC 9457 problem. Branch on code, not detail.", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer", "maximum": 599, "minimum": 400, "format": "int32" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable error code; clients branch on it. See https://entire.com/errors/. This service sends unauthenticated, forbidden, not_found, insights/not-found, insights/plugin-not-installed, method_not_allowed, invalid_request, invalid_cursor, internal_error and service_unavailable." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "HealthResponse": { "type": "object", "required": [ "status", "service", "timestamp" ], "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64" } } }, "entire-search__SearchResponse": { "type": "object", "required": [ "results", "total", "page", "timing" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "timing": { "$ref": "#/components/schemas/SearchTiming" }, "reranked": { "type": "boolean" }, "truncated": { "type": "boolean", "description": "True when results are a bounded subset rather than exhaustive: repository enumeration was capped by the repo-access resolver (ENT-1114) or the query fan-out stopped early under the per-request memory budget (ENT-1017). Retrying does not recover the remainder while the underlying cap persists." }, "truncated_types": { "$ref": "#/components/schemas/SearchTypeTruncated" }, "counts": { "$ref": "#/components/schemas/SearchTypeCounts" }, "returned_counts": { "allOf": [ { "$ref": "#/components/schemas/SearchTypeCounts" } ], "description": "Per-type tally of the RETURNED (post-fold, post-cap) result list — \"exact for what you can see\", distinct from `counts` (corpus match counts, independent of ranking/truncation). Present only on the server-side session-fold path (ENT-1595); omitted otherwise, so a client that ignores it is unaffected.\n" }, "counts_lower_bound": { "$ref": "#/components/schemas/SearchTypeCountsLowerBound" }, "partial": { "type": "boolean", "description": "True when the fan-out could not query every accessible namespace (some repos errored or timed out), so results may be incomplete. Omitted when the search was complete. A missing (404) namespace — a new or never-indexed repo — does not set this." }, "fanout": { "$ref": "#/components/schemas/FanoutStats" }, "accessible_repos": { "type": "array", "description": "The caller's broad search scope in this cell — every repo an unfiltered search would cover, independent of any repo filter on this request (ENT-1158; parity with peregrine's accessible_repos on code search). Lets the repo-filter UI offer the authoritative searchable set instead of deriving options from filter-narrowed results. Sorted by repo full name. Omitted when empty.", "items": { "$ref": "#/components/schemas/AccessibleRepo" } } } }, "AccessibleRepo": { "type": "object", "required": [ "repo", "repo_id", "provider" ], "properties": { "repo": { "type": "string", "description": "\"owner/repo\" full name." }, "repo_id": { "type": "string", "description": "Storage ULID of the repo's canonical placement." }, "provider": { "type": "string", "enum": [ "github", "entire" ], "description": "Forge namespace the repo lives in, matching the provider stamped on result rows. Rollout: servers predating this field omit it — clients must treat an absent or empty value as \"github\"." } } }, "SearchResult": { "type": "object", "required": [ "type", "data", "searchMeta" ], "properties": { "type": { "type": "string", "enum": [ "repo", "checkpoint", "commit", "pr", "session" ] }, "data": { "anyOf": [ { "$ref": "#/components/schemas/RepoResult" }, { "$ref": "#/components/schemas/CheckpointResult" }, { "$ref": "#/components/schemas/CommitResult" }, { "$ref": "#/components/schemas/PRResult" }, { "$ref": "#/components/schemas/SessionResult" } ] }, "searchMeta": { "$ref": "#/components/schemas/SearchMeta" } } }, "SearchMeta": { "type": "object", "required": [ "matchType", "score", "tier" ], "properties": { "matchType": { "type": "string", "enum": [ "keyword", "semantic", "both", "exact" ], "description": "How the result was matched. \"exact\" marks a known-item hit resolved by an exact/prefix identifier lookup (a pasted commit SHA) and pinned to the top, rather than ranked by relevance." }, "score": { "type": "number", "format": "double", "description": "Retrieval score, normalized so higher is always better. NOT the field results are ordered by — when rerankScore is present the cross-encoder decided the order, and sorting by score undoes it. Results are already returned in rank order." }, "tier": { "type": "integer", "description": "Ranking tier: 0 (exact keyword), 1 (reranked ANN), 2 (remaining ANN)" }, "snippet": { "type": "string" }, "rerankScore": { "type": "number", "format": "double", "description": "Cross-encoder relevance judgement, present only on reranked results. Where present, this is the signal the ordering was built from, and the only score comparable across repositories — bm25Score is computed per-namespace against per-repo corpus statistics." }, "bm25Score": { "type": "number", "format": "double", "description": "Raw BM25 score for the keyword leg; higher is better." }, "annScore": { "type": "number", "format": "double", "description": "Raw cosine distance for the semantic leg; LOWER is better. Inverted into a similarity before contributing to score." }, "bm25Rank": { "type": "integer" }, "annRank": { "type": "integer" }, "projected": { "type": "boolean", "description": "Marks a result synthesized from another type's document (e.g. a commit projected from a checkpoint hit) rather than a match on the type's own documents. Absent means a real match." }, "matchedIn": { "type": "string", "enum": [ "title", "transcript", "both" ], "description": "Session results only: which evidence matched — the session's AI/custom title (its session_title doc), its transcript (checkpoint chunks), or both. The server already orders title-matched sessions above transcript-only ones; clients render labels off this field without heuristics." } } }, "SearchTiming": { "type": "object", "required": [ "total_ms" ], "properties": { "total_ms": { "type": "integer", "format": "int64" }, "keyword_ms": { "type": "integer", "format": "int64", "nullable": true }, "embedding_ms": { "type": "integer", "format": "int64", "nullable": true }, "vector_ms": { "type": "integer", "format": "int64", "nullable": true }, "rerank_ms": { "type": "integer", "format": "int64", "nullable": true }, "fanout_ms": { "type": "integer", "format": "int64", "nullable": true }, "session_hydration_ms": { "type": "integer", "format": "int64", "nullable": true }, "session_names_ms": { "type": "integer", "format": "int64", "nullable": true } } }, "SearchTypeCounts": { "type": "object", "description": "True per-type match counts from a deterministic keyword + structured-filter count pass against the index, independent of ranking, Cohere reranking, and tier truncation — NOT a tally of the returned result window. commits and prs are exact document Counts (one document per entity); checkpoints and sessions are distinct-entity counts from a bounded enumeration (see counts_lower_bound); repos is the keyword-matched repo set. repos/checkpoints/commits/prs are repo-bound, and each repo has exactly one home cell (ENT-1114 one-canonical-cell guarantee), so a gateway may sum those per-cell counts across cells. sessions are the exception: a session can be cross-linked to repos in different cells, so it is deduped within a cell but summing sessions across cells may over-count a cross-cell session (bounded, and no worse than the previous per-cell behavior).", "properties": { "repos": { "type": "integer" }, "checkpoints": { "type": "integer" }, "commits": { "type": "integer" }, "prs": { "type": "integer" }, "sessions": { "type": "integer" } } }, "SearchTypeCountsLowerBound": { "type": "object", "description": "Per-facet flag marking whether the matching value in counts is a lower bound (true → render \"N+\") rather than an exact total. A facet is a lower bound when its count could not be fully accounted for: a namespace errored or timed out, the per-namespace enumeration budget was exhausted with matches remaining, or (repos) the keyword match hit its per-type cap. The zero value (false) means exact, so an absent flag defaults to exact. Composable across cells: OR the flag per facet, so any cell reporting a lower bound makes the merged facet a lower bound.", "properties": { "repos": { "type": "boolean" }, "checkpoints": { "type": "boolean" }, "commits": { "type": "boolean" }, "prs": { "type": "boolean" }, "sessions": { "type": "boolean" } } }, "SearchTypeTruncated": { "type": "object", "description": "Per-type flag marking that the returned result list for that type was capped at the per-type limit (ENT-1363): the ranked set held more results of that type than the response carries, so a tab count derived from the list is a lower bound (render \"N+\"). Only populated on the unfiltered (no filter_type) path, where per-type caps replace the global limit cut. The zero value (false) means complete. Composable across cells: OR the flag per type, together with any re-cap the gateway applies when merging.", "properties": { "repos": { "type": "boolean" }, "checkpoints": { "type": "boolean" }, "commits": { "type": "boolean" }, "prs": { "type": "boolean" }, "sessions": { "type": "boolean" } } }, "FanoutStats": { "type": "object", "description": "Per-namespace outcome counts for the query fan-out. attempted == succeeded + errored + missing + timeout.", "required": [ "attempted", "succeeded", "errored", "missing", "timeout" ], "properties": { "attempted": { "type": "integer", "description": "Accessible namespaces the fan-out tried to query." }, "succeeded": { "type": "integer", "description": "Namespaces that returned successfully (rows may be zero)." }, "errored": { "type": "integer", "description": "Namespaces whose query failed." }, "missing": { "type": "integer", "description": "Namespaces that returned 404 (new or never-indexed repo)." }, "timeout": { "type": "integer", "description": "Namespaces cut off by the fan-out deadline or cancellation." } } }, "RepoResult": { "type": "object", "required": [ "id", "githubRepoId", "org", "name", "fullName", "provider", "checkpointCount" ], "properties": { "id": { "type": "string", "description": "Placement ULID of the repo (the v4 namespace key)." }, "githubRepoId": { "type": "integer", "format": "int64", "description": "GitHub's numeric repo id from entire-core's forge identity; 0 for an entire-native repo." }, "org": { "type": "string" }, "name": { "type": "string" }, "fullName": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "entire" ], "description": "Forge namespace the repo lives in. Clients route and render by it; an entire-native row addressed as GitHub resolves names against the wrong forge. Rollout: servers predating this field omit it — clients must treat an absent or empty value as \"github\"." }, "description": { "type": "string", "nullable": true, "deprecated": true, "description": "Deprecated — always null. Its only source (the legacy repos table) was retired in ENT-1912; the field stays on the v1 wire for compatibility and will be removed in the next API version." }, "checkpointCount": { "type": "integer", "description": "entire-core's repo_facts checkpoint count (0 when unobserved)." } } }, "CheckpointResult": { "type": "object", "required": [ "id", "prompt", "branch", "org", "repo", "provider", "author", "createdAt", "filesTouched" ], "properties": { "id": { "type": "string" }, "prompt": { "type": "string" }, "commitMessage": { "type": "string", "nullable": true }, "commitSubject": { "type": "string", "nullable": true }, "commitSha": { "type": "string", "nullable": true }, "branch": { "type": "string" }, "org": { "type": "string" }, "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "entire" ], "description": "Forge namespace the repo lives in. Clients route and render by it; an entire-native row addressed as GitHub resolves names against the wrong forge. Rollout: servers predating this field omit it — clients must treat an absent or empty value as \"github\"." }, "author": { "type": "string" }, "authorUsername": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "filesTouched": { "type": "array", "items": { "type": "string" } }, "sessionId": { "type": "string", "nullable": true, "description": "First session of the checkpoint (from sessions_display), for deep-linking to /session/\u003cid\u003e#timeline-\u003ccheckpointId\u003e. Null for index docs that predate the attribute.\n" } } }, "CommitResult": { "type": "object", "required": [ "id", "commitSha", "commitMessage", "commitSubject", "branch", "org", "repo", "provider", "author", "createdAt", "additions", "deletions", "filesChanged" ], "properties": { "id": { "type": "string" }, "commitSha": { "type": "string" }, "commitMessage": { "type": "string" }, "commitSubject": { "type": "string" }, "branch": { "type": "string" }, "org": { "type": "string" }, "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "entire" ], "description": "Forge namespace the repo lives in. Clients route and render by it; an entire-native row addressed as GitHub resolves names against the wrong forge. Rollout: servers predating this field omit it — clients must treat an absent or empty value as \"github\"." }, "author": { "type": "string" }, "authorUsername": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "additions": { "type": "integer" }, "deletions": { "type": "integer" }, "filesChanged": { "type": "integer" }, "htmlUrl": { "type": "string", "nullable": true } } }, "PRResult": { "type": "object", "required": [ "id", "githubPrId", "number", "title", "state", "draft", "org", "repo", "provider", "createdAt" ], "properties": { "id": { "type": "string" }, "githubPrId": { "type": "integer", "format": "int64" }, "number": { "type": "integer" }, "title": { "type": "string" }, "htmlUrl": { "type": "string", "nullable": true }, "state": { "type": "string" }, "draft": { "type": "boolean" }, "headBranch": { "type": "string", "nullable": true }, "userLogin": { "type": "string", "nullable": true }, "org": { "type": "string" }, "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "entire" ], "description": "Forge namespace the repo lives in. Clients route and render by it; an entire-native row addressed as GitHub resolves names against the wrong forge. Rollout: servers predating this field omit it — clients must treat an absent or empty value as \"github\"." }, "createdAt": { "type": "string" }, "mergedAt": { "type": "string", "nullable": true } } }, "SessionResult": { "type": "object", "required": [ "sessionId", "displayName", "stepCount", "org", "repo", "provider", "createdAt" ], "properties": { "sessionId": { "type": "string" }, "commitSha": { "type": "string", "nullable": true, "description": "The folding checkpoint's commit sha, carried so a folded row can navigate/hydrate without a second lookup (ENT-1595). Omitted when absent.\n" }, "displayName": { "type": "string" }, "prompt": { "type": "string", "nullable": true }, "agent": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true }, "stepCount": { "type": "integer" }, "org": { "type": "string" }, "repo": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "entire" ], "description": "Forge namespace the repo lives in. Clients route and render by it; an entire-native row addressed as GitHub resolves names against the wrong forge. Rollout: servers predating this field omit it — clients must treat an absent or empty value as \"github\"." }, "branch": { "type": "string", "nullable": true }, "authorUsername": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "checkpointCount": { "type": "integer", "nullable": true, "description": "Live checkpoint count, overlaid from the cell's sessions table at query time; absent when hydration was skipped or the id was unknown." }, "kind": { "type": "string", "nullable": true, "description": "Session kind (e.g. agent_review), overlaid at query time." }, "isPublic": { "type": "boolean", "nullable": true, "description": "Public visibility, overlaid at query time." } } }, "BranchCheckView": { "additionalProperties": true, "properties": { "build_number": { "description": "The build's number within its pipeline", "format": "int64", "type": "integer" }, "commit_sha": { "description": "The commit the build ran on", "type": "string" }, "conclusion": { "description": "success or failure", "type": [ "string", "null" ] }, "finished_at": { "description": "When the build finished, if the provider said", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Check name, stable across retries", "type": "string" }, "stale": { "description": "Non-terminal and not advanced past the threshold", "type": "boolean" }, "status": { "description": "Always completed", "type": "string" }, "web_url": { "description": "The build's page at the CI provider", "type": "string" } }, "required": [ "name", "status", "conclusion", "stale", "build_number", "commit_sha", "web_url", "finished_at" ], "type": "object" }, "BranchChecksSnapshot": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/BranchChecksSnapshot.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "Branch name, without refs/heads/", "type": "string" }, "checks": { "description": "The newest finished build for each check that has one", "items": { "$ref": "#/components/schemas/BranchCheckView" }, "type": [ "array", "null" ] }, "configured": { "description": "The repo has a producer that reports checks", "type": "boolean" }, "repo_group_id": { "description": "Resolved repository group ULID, when supplied", "type": "string" } }, "required": [ "branch", "configured", "checks" ], "type": "object" }, "CheckView": { "additionalProperties": true, "properties": { "conclusion": { "description": "Set once status is completed", "type": [ "string", "null" ] }, "details_url": { "description": "Provider web URL for the reported attempt", "type": [ "string", "null" ] }, "display_name": { "description": "Suite name to show; Name stays the gate key", "type": "string" }, "finished_at": { "description": "When the selected build finished", "format": "date-time", "type": "string" }, "jobs": { "description": "Steps/jobs under the selected build", "items": { "$ref": "#/components/schemas/JobView" }, "type": [ "array", "null" ] }, "name": { "description": "Check name, stable across retries", "type": "string" }, "provider": { "description": "CI provider registry name", "type": "string" }, "provider_account": { "description": "Provider account or organization", "type": "string" }, "source": { "description": "Plugin slug", "type": "string" }, "stale": { "description": "Non-terminal and not advanced past the threshold", "type": "boolean" }, "started_at": { "description": "When the selected build started", "format": "date-time", "type": "string" }, "status": { "description": "queued, in_progress, or completed", "type": "string" } }, "required": [ "name", "status", "conclusion", "stale", "details_url" ], "type": "object" }, "ChecksSnapshot": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ChecksSnapshot.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "Branch name, without refs/heads/", "type": "string" }, "checks": { "description": "The newest attempt for each check that has run", "items": { "$ref": "#/components/schemas/CheckView" }, "type": [ "array", "null" ] }, "commit": { "description": "The commit the checks report on", "type": "string" }, "configured": { "description": "The repo has a producer that reports checks", "type": "boolean" }, "plugins": { "description": "Plugin slugs that may write checks; never null", "items": { "type": "string" }, "type": [ "array", "null" ] }, "plugins_connected_since": { "additionalProperties": { "format": "date-time", "type": "string" }, "description": "Per plugin slug, when its active installation covering the repo was installed (RFC 3339, UTC); {} when none does", "type": "object" }, "repo_group_id": { "description": "Resolved repository group ULID, when supplied", "type": "string" } }, "required": [ "commit", "branch", "configured", "plugins", "checks" ], "type": "object" }, "ci-webhooks__ErrorModel": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ErrorModel.json" ], "format": "uri", "readOnly": true, "type": "string" }, "detail": { "description": "A human-readable explanation specific to this occurrence of the problem.", "examples": [ "Property foo is required but is missing." ], "type": "string" }, "errors": { "description": "Optional list of individual error details", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": [ "array", "null" ] }, "instance": { "description": "A URI reference that identifies the specific occurrence of the problem.", "examples": [ "https://example.com/error-log/abc123" ], "format": "uri", "type": "string" }, "status": { "description": "HTTP status code", "examples": [ 400 ], "format": "int64", "type": "integer" }, "title": { "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.", "examples": [ "Bad Request" ], "type": "string" }, "type": { "default": "about:blank", "description": "A URI reference to human-readable documentation for the error.", "examples": [ "https://example.com/errors/example" ], "format": "uri", "type": "string" } }, "type": "object" }, "JobView": { "additionalProperties": true, "properties": { "bk_job_id": { "description": "Provider job identifier", "type": "string" }, "exit_status": { "description": "Command exit status once finished", "format": "int64", "type": "integer" }, "finished_at": { "description": "When the job finished (UTC)", "format": "date-time", "type": "string" }, "name": { "description": "Step label", "type": "string" }, "started_at": { "description": "When the job started (UTC)", "format": "date-time", "type": "string" }, "state": { "description": "Job state", "type": "string" }, "step_key": { "description": "Pipeline step key, if the step set one", "type": "string" }, "type": { "description": "Job type (script, trigger, manual, ...)", "type": "string" } }, "required": [ "bk_job_id", "type", "name", "step_key", "state" ], "type": "object" }, "ListPluginDeliveriesOutputBody": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ListPluginDeliveriesOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "deliveries": { "items": { "$ref": "#/components/schemas/PluginDeliveryView" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor for the next page; absent on the last page", "type": "string" } }, "required": [ "deliveries" ], "type": "object" }, "PluginDeliveryAttemptView": { "additionalProperties": true, "properties": { "attempt": { "description": "Attempt number, from 1", "format": "int64", "type": "integer" }, "duration_ms": { "description": "How long the attempt took, milliseconds", "format": "int64", "type": "integer" }, "endpoint": { "description": "URL the attempt posted to", "type": "string" }, "error": { "description": "Transport or policy error; empty on a response", "type": "string" }, "response_body": { "description": "Response body, cut at the stored limit", "type": "string" }, "response_headers": { "additionalProperties": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "description": "Response headers; absent with no response", "type": "object" }, "response_status": { "description": "HTTP status; absent when no response arrived", "format": "int64", "type": "integer" }, "started_at": { "description": "When the POST started, UTC", "format": "date-time", "type": "string" } }, "required": [ "attempt", "started_at", "endpoint", "response_body", "duration_ms" ], "type": "object" }, "PluginDeliveryDetailView": { "additionalProperties": true, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/PluginDeliveryDetailView.json" ], "format": "uri", "readOnly": true, "type": "string" }, "attempt_count": { "description": "Attempts claimed so far, including one in flight", "format": "int64", "type": "integer" }, "attempts": { "description": "Recorded attempts, oldest first", "items": { "$ref": "#/components/schemas/PluginDeliveryAttemptView" }, "type": [ "array", "null" ] }, "completed_at": { "description": "When the delivery reached delivered or failed, UTC", "format": "date-time", "type": "string" }, "created_at": { "description": "When the event was enqueued, UTC", "format": "date-time", "type": "string" }, "event_type": { "description": "Event type, e.g. ref.updated", "type": "string" }, "id": { "description": "Delivery id; the delivery_id in the payload sent to the plugin", "type": "string" }, "installation_id": { "description": "Installation the event was delivered for", "type": "string" }, "last_response_status": { "description": "HTTP status of the latest recorded attempt; absent when it got no response or none ran", "format": "int64", "type": "integer" }, "outcome": { "description": "Why the delivery reached its state; empty while it has none", "type": "string" }, "request": { "$ref": "#/components/schemas/PluginDeliveryRequestView" }, "state": { "description": "pending, in_flight, delivered or failed", "type": "string" } }, "required": [ "request", "attempts", "id", "installation_id", "event_type", "state", "attempt_count", "created_at" ], "type": "object" }, "PluginDeliveryRequestView": { "additionalProperties": true, "properties": { "body": { "description": "Request body", "type": "string" }, "headers": { "additionalProperties": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "description": "Request headers, without Authorization", "type": "object" } }, "required": [ "headers", "body" ], "type": "object" }, "PluginDeliveryView": { "additionalProperties": true, "properties": { "attempt_count": { "description": "Attempts claimed so far, including one in flight", "format": "int64", "type": "integer" }, "completed_at": { "description": "When the delivery reached delivered or failed, UTC", "format": "date-time", "type": "string" }, "created_at": { "description": "When the event was enqueued, UTC", "format": "date-time", "type": "string" }, "event_type": { "description": "Event type, e.g. ref.updated", "type": "string" }, "id": { "description": "Delivery id; the delivery_id in the payload sent to the plugin", "type": "string" }, "installation_id": { "description": "Installation the event was delivered for", "type": "string" }, "last_response_status": { "description": "HTTP status of the latest recorded attempt; absent when it got no response or none ran", "format": "int64", "type": "integer" }, "outcome": { "description": "Why the delivery reached its state; empty while it has none", "type": "string" }, "state": { "description": "pending, in_flight, delivered or failed", "type": "string" } }, "required": [ "id", "installation_id", "event_type", "state", "attempt_count", "created_at" ], "type": "object" }, "PluginProject": { "additionalProperties": true, "properties": { "forge": { "enum": [ "entire", "github" ], "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "forge" ], "type": "object" }, "PluginWebhookAccount": { "additionalProperties": true, "properties": { "handle": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "handle" ], "type": "object" }, "PluginWebhookDelivery": { "additionalProperties": true, "properties": { "api_url": { "description": "The delivering cell's Entire API, where this repository's check runs go.", "type": "string" }, "core_url": { "description": "The delivering cell's Entire core.", "type": "string" }, "delivery_id": { "description": "Unique to this delivery and the same across retries. Deduplicate on it.", "type": "string" }, "event": { "$ref": "#/components/schemas/PluginWebhookEvent" }, "installation_id": { "type": "string" }, "plugin_id": { "description": "Your plugin slug.", "type": "string" } }, "required": [ "delivery_id", "plugin_id", "installation_id", "core_url", "api_url", "event" ], "type": "object" }, "PluginWebhookEvent": { "additionalProperties": true, "properties": { "id": { "description": "The same for every installation that receives this event.", "type": "string" }, "payload": { "$ref": "#/components/schemas/PluginWebhookRefPush" }, "time": { "format": "date-time", "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "time", "payload" ], "type": "object" }, "PluginWebhookInstallationDelivery": { "additionalProperties": true, "properties": { "api_url": { "description": "The delivering cell's Entire API.", "type": "string" }, "core_url": { "description": "The delivering cell's Entire core.", "type": "string" }, "delivery_id": { "description": "Derived from the event, so it is the same across retries. Deduplicate on it.", "type": "string" }, "event": { "$ref": "#/components/schemas/PluginWebhookInstallationEventBody" }, "installation_id": { "type": "string" }, "plugin_id": { "description": "Your plugin slug.", "type": "string" } }, "required": [ "delivery_id", "plugin_id", "installation_id", "core_url", "api_url", "event" ], "type": "object" }, "PluginWebhookInstallationEventBody": { "additionalProperties": true, "properties": { "id": { "description": "Derived from the event, so it is the same across retries.", "type": "string" }, "payload": { "$ref": "#/components/schemas/PluginWebhookInstallationPayload" }, "time": { "format": "date-time", "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "time", "payload" ], "type": "object" }, "PluginWebhookInstallationPayload": { "additionalProperties": true, "properties": { "installation": { "$ref": "#/components/schemas/PluginWebhookInstallationState" } }, "required": [ "installation" ], "type": "object" }, "PluginWebhookInstallationState": { "additionalProperties": true, "properties": { "added_repository_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "manage_url": { "description": "The web app page where the customer manages the installation. Absent on installation.deleted, and when core cannot build it.", "type": "string" }, "project": { "allOf": [ { "description": "Public project identity. May be absent if its route cannot resolve. Use id as the stable key." }, { "$ref": "#/components/schemas/PluginProject" } ] }, "project_id": { "type": "string" }, "removed_repository_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "repositories_omitted": { "description": "True when the list was too long to include. List the installation's repositories instead.", "type": "boolean" }, "repository_count": { "format": "int64", "type": "integer" }, "repository_ids": { "description": "Absent when the event does not carry the list.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "repository_selection": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "suspended_by": { "type": "string" } }, "required": [ "project_id", "revision" ], "type": "object" }, "PluginWebhookPusher": { "additionalProperties": true, "properties": { "account": { "$ref": "#/components/schemas/PluginWebhookAccount" } }, "required": [ "account" ], "type": [ "object", "null" ] }, "PluginWebhookRefPush": { "additionalProperties": true, "properties": { "after": { "description": "Object ID after the change. All zeros on delete.", "type": "string" }, "before": { "description": "Object ID before the change. All zeros on create.", "type": "string" }, "forced": { "type": "boolean" }, "pusher": { "allOf": [ { "description": "Null when Entire does not know who pushed." }, { "$ref": "#/components/schemas/PluginWebhookPusher" } ] }, "ref": { "type": "string" }, "repository": { "$ref": "#/components/schemas/PluginWebhookRepository" } }, "required": [ "repository", "ref", "before", "after", "forced", "pusher" ], "type": "object" }, "PluginWebhookRepository": { "additionalProperties": true, "properties": { "clone_url": { "type": "string" }, "default_branch": { "type": "string" }, "entire_clone_url": { "type": "string" }, "id": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "path", "default_branch", "clone_url", "entire_clone_url" ], "type": "object" }, "PluginWebhookTrail": { "additionalProperties": true, "properties": { "author": { "allOf": [ { "description": "Null when Entire does not know who opened the trail." }, { "$ref": "#/components/schemas/PluginWebhookTrailActor" } ] }, "base": { "description": "The branch the trail merges into.", "type": "string" }, "branch": { "description": "The branch the trail tracks. Null once the trail released its branch.", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "head_sha": { "description": "The commit Entire last recorded for the branch. Null until Entire records one.", "type": [ "string", "null" ] }, "id": { "description": "The trail's id. It does not change.", "type": "string" }, "merged_at": { "description": "Set on a merged trail only.", "format": "date-time", "type": "string" }, "number": { "description": "The trail's number in its repository.", "format": "int64", "type": "integer" }, "state": { "description": "draft, open, closed or merged.", "enum": [ "draft", "open", "closed", "merged" ], "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "number", "title", "state", "branch", "base", "head_sha", "author", "created_at", "updated_at" ], "type": "object" }, "PluginWebhookTrailAccount": { "additionalProperties": true, "properties": { "id": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "PluginWebhookTrailActor": { "additionalProperties": true, "properties": { "account": { "$ref": "#/components/schemas/PluginWebhookTrailAccount" } }, "required": [ "account" ], "type": [ "object", "null" ] }, "PluginWebhookTrailChange": { "additionalProperties": true, "properties": { "from": { "description": "The value before the change. Null when there was none.", "type": [ "string", "null" ] }, "to": { "description": "The value after the change. Null when there is none.", "type": [ "string", "null" ] } }, "required": [ "from", "to" ], "type": "object" }, "PluginWebhookTrailChanges": { "additionalProperties": true, "properties": { "base": { "$ref": "#/components/schemas/PluginWebhookTrailChange" }, "branch": { "$ref": "#/components/schemas/PluginWebhookTrailChange" }, "head_sha": { "$ref": "#/components/schemas/PluginWebhookTrailChange" }, "state": { "$ref": "#/components/schemas/PluginWebhookTrailChange" }, "title": { "$ref": "#/components/schemas/PluginWebhookTrailChange" } }, "type": "object" }, "PluginWebhookTrailDelivery": { "additionalProperties": true, "properties": { "api_url": { "description": "The delivering cell's Entire API, where this repository's check runs go.", "type": "string" }, "core_url": { "description": "The delivering cell's Entire core.", "type": "string" }, "delivery_id": { "description": "Unique to this delivery and the same across retries. Deduplicate on it.", "type": "string" }, "event": { "$ref": "#/components/schemas/PluginWebhookTrailEventBody" }, "installation_id": { "type": "string" }, "plugin_id": { "description": "Your plugin slug.", "type": "string" } }, "required": [ "delivery_id", "plugin_id", "installation_id", "core_url", "api_url", "event" ], "type": "object" }, "PluginWebhookTrailEventBody": { "additionalProperties": true, "properties": { "id": { "description": "The same for every installation that receives this event.", "type": "string" }, "payload": { "$ref": "#/components/schemas/PluginWebhookTrailPayload" }, "time": { "format": "date-time", "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "time", "payload" ], "type": "object" }, "PluginWebhookTrailPayload": { "additionalProperties": true, "properties": { "actor": { "allOf": [ { "description": "Who made the change. Null when Entire does not know, such as for a push or a change on the forge." }, { "$ref": "#/components/schemas/PluginWebhookTrailActor" } ] }, "changes": { "allOf": [ { "description": "The fields this event changed. Absent on trail.opened." }, { "$ref": "#/components/schemas/PluginWebhookTrailChanges" } ] }, "repository": { "$ref": "#/components/schemas/PluginWebhookTrailRepository" }, "trail": { "$ref": "#/components/schemas/PluginWebhookTrail" } }, "required": [ "repository", "trail", "actor" ], "type": "object" }, "PluginWebhookTrailRepository": { "additionalProperties": true, "properties": { "clone_url": { "type": "string" }, "entire_clone_url": { "type": "string" }, "id": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "path", "clone_url", "entire_clone_url" ], "type": "object" }, "Anchor": { "type": "object", "description": "One provenance anchor (camelCase read-model projection).", "properties": { "sessionId": { "type": "string" }, "commit": { "type": "string" }, "checkpointId": { "type": "string" }, "turnId": { "type": "string" }, "verified": { "type": "boolean" } } }, "MemoryItem": { "type": "object", "description": "One memories read-model row, shared by listMemories and queryMemories.", "properties": { "factId": { "type": "string" }, "text": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "supersededBy": { "type": "string", "description": "Fact id of the superseding fact; empty unless status is superseded." }, "trailId": { "type": "string", "description": "Merged trail this fact belongs to; empty until its trail merges." }, "paths": { "type": "array", "items": { "type": "string" } }, "locus": { "type": "array", "items": { "type": "string" }, "description": "Code identifiers/paths the fact is about." }, "provenance": { "type": "array", "items": { "$ref": "#/components/schemas/Anchor" }, "description": "Source anchors; the UI shows the commit a memory came from." }, "createdBy": { "type": "string" }, "createdByHandle": { "type": "string", "description": "Server-stamped display handle; attribution only, never an authz input." }, "lastActionBy": { "type": "string" }, "createdAt": { "type": "string", "description": "Server stamp (ISO 8601, milliseconds)." }, "updatedAt": { "type": "string", "description": "Server stamp (ISO 8601, milliseconds)." }, "recordCreatedAt": { "type": "string", "description": "Client-side creation time of the record (ISO 8601, milliseconds); can precede upload." }, "accepted": { "type": "boolean", "description": "A reviewer kept this fact (see :accept). Review state, not a lifecycle status; never synced." } } }, "FactRecord": { "type": "object", "description": "entire-brain factmerge wire record, embedded whole (snake_case; a foreign wire contract, never flattened into the camelCase envelope). created_at/updated_at are the client's own wire values.", "properties": { "id": { "type": "string", "description": "Content-derived fact id (\"fact:\" + sha256 of normalized text + sorted paths)." }, "paths": { "type": "array", "items": { "type": "string" } }, "kind": { "type": "string" }, "locus": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" }, "branch": { "type": "string", "description": "Display metadata only; never a storage key." }, "origin": { "type": "string", "enum": [ "distilled", "authored" ] }, "agent": { "type": "string", "description": "Extraction agent that distilled the fact; empty for authored facts." }, "model": { "type": "string", "description": "Extraction model that generated the fact; empty for authored facts." }, "effort": { "type": "string", "description": "Extraction effort setting; empty for authored facts." }, "status": { "type": "string", "enum": [ "active", "superseded", "retracted" ] }, "confidence": { "type": "string" }, "related_ids": { "type": "array", "items": { "type": "string" } }, "superseded_by": { "type": "string" }, "provenance": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string" }, "commit": { "type": "string" }, "checkpoint_id": { "type": "string" }, "turn_id": { "type": "string" }, "verified": { "type": "boolean" } } } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "ActivityAgentRollup": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "checkpoint_count": { "format": "int64", "type": "integer" }, "steps": { "format": "int64", "type": "integer" } }, "required": [ "agent", "checkpoint_count", "steps" ], "type": "object" }, "ActivityBucket": { "additionalProperties": false, "properties": { "checkpoint_count": { "format": "int64", "type": "integer" }, "commit_count": { "format": "int64", "type": "integer" }, "date": { "type": "string" } }, "required": [ "date", "commit_count", "checkpoint_count" ], "type": "object" }, "ActivityBucketsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ActivityBucketsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "buckets": { "items": { "$ref": "#/components/schemas/BucketItem" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "timeframe": { "type": "string" } }, "required": [ "buckets", "timeframe", "meta" ], "type": "object" }, "ActivityOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ActivityOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agents": { "items": { "$ref": "#/components/schemas/ActivityAgentRollup" }, "type": [ "array", "null" ] }, "buckets": { "items": { "$ref": "#/components/schemas/ActivityBucket" }, "type": [ "array", "null" ] }, "in_progress": { "$ref": "#/components/schemas/StateCounts" }, "meta": { "$ref": "#/components/schemas/Meta" }, "repos": { "items": { "$ref": "#/components/schemas/ActivityRepoRollup" }, "type": [ "array", "null" ] }, "shipped": { "$ref": "#/components/schemas/StateCounts" }, "streak": { "$ref": "#/components/schemas/StreakStruct" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "buckets", "repos", "agents", "shipped", "in_progress", "streak", "updated_at", "meta" ], "type": "object" }, "ActivityRepoRollup": { "additionalProperties": false, "properties": { "checkpoint_count": { "format": "int64", "type": "integer" }, "commit_count": { "format": "int64", "type": "integer" }, "repo_id": { "type": "string" } }, "required": [ "repo_id", "commit_count", "checkpoint_count" ], "type": "object" }, "Agent": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/Agent.json" ], "format": "uri", "readOnly": true, "type": "string" }, "archived_at": { "description": "When the agent was archived; null while active.", "format": "date-time", "type": [ "string", "null" ] }, "archived_by": { "allOf": [ { "description": "Who archived the agent; present only once archived." }, { "$ref": "#/components/schemas/ConfigActor" } ] }, "created_at": { "description": "When version 1 was saved.", "format": "date-time", "type": "string" }, "created_by": { "allOf": [ { "description": "Who saved version 1; each version records its own author." }, { "$ref": "#/components/schemas/ConfigActor" } ] }, "description": { "description": "Free-form description; empty when unset.", "type": "string" }, "environment_id": { "description": "The project environment (ULID) the agent runs in.", "type": "string" }, "etag": { "description": "Write token. Copy this JSON value unchanged into If-Match when replacing, archiving or restoring. Prefer it to the HTTP ETag header, which intermediaries may transform.", "type": "string" }, "harness": { "description": "Agent CLI that runs the instructions.", "type": "string" }, "id": { "description": "Agent id (ULID); stable across versions, a customization and a restore. Runs, a Change's agents and review comments name the agent by it.", "type": "string" }, "instructions": { "description": "Review focus, rendered after the review contract's guidance.", "type": "string" }, "is_enabled": { "description": "Whether its trigger runs it. Manual runs ignore it: a paused agent still runs when asked to.", "type": "boolean" }, "model": { "description": "Model passed to the harness; null uses the harness default.", "type": [ "string", "null" ] }, "name": { "description": "Display name, unique among the project's active agents (ignoring case). A preset agent's is its preset's.", "type": "string" }, "preset": { "allOf": [ { "description": "The Entire preset the agent runs, or null for a custom agent. A preset agent's name, description, model, instructions and signal are the preset's as it is now, read on every read and run; to change them, replace the agent with preset null and every field (it keeps its id)." }, { "$ref": "#/components/schemas/AgentPresetRef" } ] }, "project_id": { "description": "Owning project id (ULID).", "type": "string" }, "reasoning_effort": { "description": "Reasoning effort the agent runs at. Null when its model takes none, or for a version saved before efforts were stored, which runs at the harness default.", "type": [ "string", "null" ] }, "repository_ids": { "description": "The selected repositories of the project (ULIDs), in the order saved.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "signal": { "allOf": [ { "description": "The agent's signal: each review distilled into one reading. It has no name of its own; a Change shows it under the agent's name." }, { "$ref": "#/components/schemas/AgentSignal" } ] }, "stale_repository_ids": { "description": "The subset of repository_ids this cell no longer records as repositories of the project — transferred to another project, deleted, or unknown here — read now, not saved. They grant nothing; replace the agent without them to repair the selection. Not covered by the ETag.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "timeout_ms": { "description": "Agent process time limit, in milliseconds.", "format": "int64", "type": "integer" }, "triggers": { "description": "Zero or one trigger; empty means the agent only runs when asked to. Push triggers run when the push listener is enabled.", "items": { "$ref": "#/components/schemas/AgentTrigger" }, "type": [ "array", "null" ] }, "updated_at": { "description": "When the last version was saved, or the agent was archived or restored.", "format": "date-time", "type": "string" }, "version": { "description": "Current version.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "id", "project_id", "version", "etag", "stale_repository_ids", "created_at", "created_by", "updated_at", "archived_at", "preset", "is_enabled", "environment_id", "repository_ids", "triggers", "name", "description", "harness", "model", "reasoning_effort", "timeout_ms", "instructions", "signal" ], "type": "object" }, "AgentActivityDayItem": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "count": { "format": "int64", "type": "integer" }, "date": { "type": "string" }, "inputTokens": { "format": "int64", "type": "integer" }, "outputTokens": { "format": "int64", "type": "integer" }, "tokens": { "format": "int64", "type": "integer" } }, "required": [ "date", "agent", "count", "tokens", "inputTokens", "outputTokens" ], "type": "object" }, "AgentContributions": { "additionalProperties": false, "properties": { "amp": { "format": "int64", "type": "integer" }, "antigravity": { "format": "int64", "type": "integer" }, "claude": { "format": "int64", "type": "integer" }, "codex": { "format": "int64", "type": "integer" }, "copilot": { "format": "int64", "type": "integer" }, "cursor": { "format": "int64", "type": "integer" }, "droid": { "format": "int64", "type": "integer" }, "gemini": { "format": "int64", "type": "integer" }, "goose": { "format": "int64", "type": "integer" }, "kiro": { "format": "int64", "type": "integer" }, "opencode": { "format": "int64", "type": "integer" }, "pi": { "format": "int64", "type": "integer" }, "unknown": { "format": "int64", "type": "integer" } }, "required": [ "claude", "gemini", "amp", "codex", "opencode", "copilot", "pi", "cursor", "droid", "kiro", "antigravity", "goose", "unknown" ], "type": "object" }, "AgentCreate": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AgentCreate.json" ], "format": "uri", "readOnly": true, "type": "string" }, "description": { "description": "Free-form description.", "maxLength": 1024, "type": "string" }, "environment": { "allOf": [ { "description": "A new environment, with the fields of an environment create, saved with the agent as an ordinary, reusable project environment. Send exactly one of environment_id and environment." }, { "$ref": "#/components/schemas/EnvironmentFieldsInput" } ] }, "environment_id": { "description": "An existing active environment of the project (ULID). Send exactly one of environment_id and environment.", "type": "string" }, "harness": { "description": "Agent CLI that runs the instructions. Required without a preset.", "enum": [ "claude", "codex" ], "type": "string" }, "instructions": { "description": "Review focus. Supports {{branch}} and {{base_branch}} placeholders. Required without a preset.", "maxLength": 16384, "type": "string" }, "is_enabled": { "description": "Whether its trigger runs it. Defaults to false. Manual runs ignore it.", "type": "boolean" }, "model": { "description": "Model passed to the harness: an id GET /agents/models lists for it. Omit or send null for the harness default.", "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "name": { "description": "Display name, without surrounding whitespace, unique among the project's active agents (ignoring case). Required without a preset.", "maxLength": 128, "type": "string" }, "preset": { "description": "Run an Entire preset (GET /agents/presets) as it is now: its name, description, model, instructions and signal are the preset's, on every read and run. Send null or omit it for a custom agent. One active agent per preset per project.", "maxLength": 64, "minLength": 1, "type": [ "string", "null" ] }, "reasoning_effort": { "description": "Reasoning effort: one of the reasoning_efforts GET /agents/models lists for the model the agent runs (the harness default model when model is null). Any other value returns 422. Omit or send null to save the harness's default_reasoning_effort, or none when the model takes none.", "enum": [ "low", "medium", "high", "xhigh", "max", "ultra" ], "type": [ "string", "null" ] }, "repository_ids": { "description": "1–100 distinct repository ids (ULIDs) of the project. Each must be a repository of the project in this cell, and the caller needs repository push on each.", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] }, "signal": { "allOf": [ { "description": "The signal each review reports with its findings: the review distilled into one reading. Required without a preset." }, { "$ref": "#/components/schemas/AgentSignalInput" } ] }, "timeout_ms": { "description": "Agent process time limit, in milliseconds. Required without a preset.", "format": "int64", "maximum": 1800000, "minimum": 1, "type": "integer" }, "triggers": { "description": "At most one trigger. Omit or send [] for an agent that only runs when asked to.", "items": { "$ref": "#/components/schemas/AgentTriggerInput" }, "maxItems": 1, "type": [ "array", "null" ] } }, "required": [ "repository_ids" ], "type": "object" }, "AgentDefinition": { "additionalProperties": false, "properties": { "description": { "description": "Free-form description; empty when unset.", "type": "string" }, "harness": { "description": "Agent CLI that runs the instructions.", "type": "string" }, "instructions": { "description": "Review focus, rendered after the review contract's guidance.", "type": "string" }, "model": { "description": "Model passed to the harness; null uses the harness default.", "type": [ "string", "null" ] }, "name": { "description": "Display name, unique among the project's active agents (ignoring case). A preset agent's is its preset's.", "type": "string" }, "reasoning_effort": { "description": "Reasoning effort the agent runs at. Null when its model takes none, or for a version saved before efforts were stored, which runs at the harness default.", "type": [ "string", "null" ] }, "signal": { "allOf": [ { "description": "The agent's signal: each review distilled into one reading. It has no name of its own; a Change shows it under the agent's name." }, { "$ref": "#/components/schemas/AgentSignal" } ] }, "timeout_ms": { "description": "Agent process time limit, in milliseconds.", "format": "int64", "type": "integer" } }, "required": [ "name", "description", "harness", "model", "reasoning_effort", "timeout_ms", "instructions", "signal" ], "type": "object" }, "AgentHarnessModels": { "additionalProperties": false, "properties": { "default_model": { "description": "Model id a run uses when the agent's model is null.", "type": "string" }, "default_reasoning_effort": { "description": "Reasoning effort a run uses when the agent sets none; null when the harness sets none.", "type": [ "string", "null" ] }, "harness": { "description": "Agent CLI the models run under.", "enum": [ "claude", "codex" ], "type": "string" }, "models": { "description": "Models the picker offers for this harness, current ones first, then more. Hidden models are omitted but still accepted on save.", "items": { "$ref": "#/components/schemas/AgentModel" }, "type": [ "array", "null" ] }, "reasoning_efforts": { "description": "Every reasoning_effort value some model of this harness accepts, hidden models included, lowest first; empty when the harness takes none. A model's own reasoning_efforts is what an agent using it may set.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "harness", "default_model", "default_reasoning_effort", "reasoning_efforts", "models" ], "type": "object" }, "AgentModel": { "additionalProperties": false, "properties": { "id": { "description": "Model id, as an agent's model field takes it.", "type": "string" }, "name": { "description": "Display name.", "type": "string" }, "reasoning_efforts": { "description": "Accepted reasoning_effort values for an agent using this model, lowest first; empty when the model takes none.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "visibility": { "description": "Whether the picker shows the model in the current lineup or under more models.", "enum": [ "current", "more" ], "type": "string" } }, "required": [ "id", "name", "visibility", "reasoning_efforts" ], "type": "object" }, "AgentModels": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AgentModels.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agents": { "description": "One entry per harness an agent can use.", "items": { "$ref": "#/components/schemas/AgentHarnessModels" }, "type": [ "array", "null" ] } }, "required": [ "agents" ], "type": "object" }, "AgentNameJSON": { "additionalProperties": false, "properties": { "id": { "description": "Agent id (GET .../agents/{id}).", "type": "string" }, "name": { "description": "The agent's current name.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "AgentOutputSourceJSON": { "additionalProperties": false, "properties": { "agent": { "allOf": [ { "description": "The agent (GET .../agents/{id}), by its current name." }, { "$ref": "#/components/schemas/AgentNameJSON" } ] }, "run_id": { "description": "The run that published it (GET .../runs/{id}).", "type": "string" } }, "required": [ "agent", "run_id" ], "type": "object" }, "AgentPreset": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AgentPreset.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agent": { "allOf": [ { "description": "What an agent of the preset runs and is called, as it is now: every agent of the preset follows it." }, { "$ref": "#/components/schemas/AgentDefinition" } ] }, "description": { "description": "What an agent of the preset does.", "type": "string" }, "id": { "description": "Stable preset id.", "type": "string" }, "name": { "description": "Display name of the preset, and of every agent that runs it.", "type": "string" }, "sha256": { "description": "SHA-256 of the preset's current content (name, description and what it runs), as a run records it.", "type": "string" }, "version": { "description": "The preset's current version; it changes whenever its content does. A run of a preset agent records the version it ran.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "id", "version", "sha256", "name", "description", "agent" ], "type": "object" }, "AgentPresetRef": { "additionalProperties": false, "properties": { "id": { "description": "Preset id (GET /agents/presets).", "type": "string" }, "version": { "description": "The preset's current version: what the agent's next run will run. A run records the version it ran.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "id", "version" ], "type": "object" }, "AgentReplace": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AgentReplace.json" ], "format": "uri", "readOnly": true, "type": "string" }, "description": { "description": "Free-form description.", "maxLength": 1024, "type": "string" }, "environment_id": { "description": "An active environment of the project (ULID). Inline environments are create-only.", "type": "string" }, "harness": { "description": "Agent CLI that runs the instructions. Required without a preset.", "enum": [ "claude", "codex" ], "type": "string" }, "instructions": { "description": "Review focus. Supports {{branch}} and {{base_branch}} placeholders. Required without a preset.", "maxLength": 16384, "type": "string" }, "is_enabled": { "description": "Whether its trigger runs it. Defaults to false. Manual runs ignore it.", "type": "boolean" }, "model": { "description": "Model passed to the harness: an id GET /agents/models lists for it. Omit or send null for the harness default.", "maxLength": 128, "minLength": 1, "type": [ "string", "null" ] }, "name": { "description": "Display name, without surrounding whitespace, unique among the project's active agents (ignoring case). Required without a preset.", "maxLength": 128, "type": "string" }, "preset": { "description": "Run an Entire preset (GET /agents/presets) as it is now: its name, description, model, instructions and signal are the preset's, on every read and run. Send null or omit it for a custom agent. One active agent per preset per project.", "maxLength": 64, "minLength": 1, "type": [ "string", "null" ] }, "reasoning_effort": { "description": "Reasoning effort: one of the reasoning_efforts GET /agents/models lists for the model the agent runs (the harness default model when model is null). Any other value returns 422. Omit or send null to save the harness's default_reasoning_effort, or none when the model takes none.", "enum": [ "low", "medium", "high", "xhigh", "max", "ultra" ], "type": [ "string", "null" ] }, "repository_ids": { "description": "1–100 distinct repository ids (ULIDs) of the project. Each must be a repository of the project in this cell, and the caller needs repository push on each.", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] }, "signal": { "allOf": [ { "description": "The signal each review reports with its findings: the review distilled into one reading. Required without a preset." }, { "$ref": "#/components/schemas/AgentSignalInput" } ] }, "timeout_ms": { "description": "Agent process time limit, in milliseconds. Required without a preset.", "format": "int64", "maximum": 1800000, "minimum": 1, "type": "integer" }, "triggers": { "description": "At most one trigger. Omit or send [] for an agent that only runs when asked to.", "items": { "$ref": "#/components/schemas/AgentTriggerInput" }, "maxItems": 1, "type": [ "array", "null" ] } }, "required": [ "environment_id", "repository_ids" ], "type": "object" }, "AgentSignal": { "additionalProperties": false, "properties": { "polarity": { "description": "Which readings are good.", "enum": [ "higher_is_better", "lower_is_better", "neutral" ], "type": "string" }, "value_type": { "description": "boolean (true/false), percent (0-100) or size (small, medium, large).", "enum": [ "boolean", "percent", "size" ], "type": "string" } }, "required": [ "value_type", "polarity" ], "type": "object" }, "AgentSignalInput": { "additionalProperties": false, "properties": { "polarity": { "description": "Which readings are good. Omit or send null for neutral; the agent stores it explicitly.", "enum": [ "higher_is_better", "lower_is_better", "neutral" ], "type": [ "string", "null" ] }, "value_type": { "description": "boolean (true/false), percent (0-100) or size (small, medium, large).", "enum": [ "boolean", "percent", "size" ], "type": "string" } }, "required": [ "value_type" ], "type": "object" }, "AgentTrigger": { "additionalProperties": false, "properties": { "branches": { "description": "Branch name globs (main, release/*, feature/**): the trigger runs only on a Change whose branch one matches; empty, every branch. * matches within one segment of a slash-separated name, ? one character in one, ** as a whole segment any number of segments; anything else is literal and case-sensitive.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "description": "Stable trigger id, unique in the agent. Push runs are deduplicated per trigger id.", "type": "string" }, "kind": { "description": "push: run on a push to a branch with an open Change in a selected repository, as when admits it.", "enum": [ "push" ], "type": "string" }, "paths": { "description": "Repository path globs (frontend/**, **/*.go), in the syntax of branches: the trigger runs only on a Change that changes a path one matches, over the whole Change from its merge base with its base branch to its head (a renamed file under both names); empty, every Change. A Change too large for the host to list in full runs unless the part listed already matches. Manual runs ignore both filters.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "when": { "description": "Which Changes the push trigger runs on, by readiness for review. ready: only a Change ready for review, including when one becomes ready. always: every push, ready or not. not_ready: only a Change not yet ready for review. A Change is ready once marked ready for review, which a GitHub pull request is not while it is a draft. In a repository without an approvals gate, which keeps no readiness, every open Change is ready, so not_ready never runs there.", "enum": [ "ready", "always", "not_ready" ], "type": "string" } }, "required": [ "id", "kind", "when", "branches", "paths" ], "type": "object" }, "AgentTriggerInput": { "additionalProperties": false, "properties": { "branches": { "description": "Branch name globs (main, release/*, feature/**): the trigger runs only on a Change whose branch one matches; empty, every branch. * matches within one segment of a slash-separated name, ? one character in one, ** as a whole segment any number of segments; anything else is literal and case-sensitive. At most 32 patterns of at most 256 bytes, each relative (no leading or trailing /, no empty segment, not refs/...), with ** only as a whole segment. Omit or send [] for every branch.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "description": "Stable id, unique in the agent: lowercase letters, digits, - and _. Defaults to the kind. Keep it to keep the trigger's push history.", "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_-]*$", "type": "string" }, "kind": { "description": "push: run on a push to a branch with an open Change in a selected repository, as when admits it.", "enum": [ "push" ], "type": "string" }, "paths": { "description": "Repository path globs (frontend/**, **/*.go), in the syntax of branches: the trigger runs only on a Change that changes a path one matches, over the whole Change from its merge base with its base branch to its head (a renamed file under both names); empty, every Change. A Change too large for the host to list in full runs unless the part listed already matches. The limits of branches apply. Omit or send [] for every Change. Manual runs ignore both filters.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "when": { "description": "Which Changes the push trigger runs on, by readiness for review. ready: only a Change ready for review, including when one becomes ready. always: every push, ready or not. not_ready: only a Change not yet ready for review. A Change is ready once marked ready for review, which a GitHub pull request is not while it is a draft. In a repository without an approvals gate, which keeps no readiness, every open Change is ready, so not_ready never runs there. Defaults to ready; push triggers only.", "enum": [ "ready", "always", "not_ready" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "AgentVersion": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AgentVersion.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agent_id": { "description": "Agent id (ULID) this version belongs to.", "type": "string" }, "created_at": { "description": "When this version was saved.", "format": "date-time", "type": "string" }, "created_by": { "allOf": [ { "description": "Who saved this version." }, { "$ref": "#/components/schemas/ConfigActor" } ] }, "description": { "description": "Free-form description; empty when unset.", "type": "string" }, "environment_id": { "description": "The project environment (ULID) the agent runs in.", "type": "string" }, "harness": { "description": "Agent CLI that runs the instructions.", "type": "string" }, "instructions": { "description": "Review focus, rendered after the review contract's guidance.", "type": "string" }, "is_enabled": { "description": "Whether its trigger runs it. Manual runs ignore it: a paused agent still runs when asked to.", "type": "boolean" }, "model": { "description": "Model passed to the harness; null uses the harness default.", "type": [ "string", "null" ] }, "name": { "description": "Display name, unique among the project's active agents (ignoring case). A preset agent's is its preset's.", "type": "string" }, "preset": { "allOf": [ { "description": "The Entire preset the agent runs, or null for a custom agent. A preset agent's name, description, model, instructions and signal are the preset's as it is now, read on every read and run; to change them, replace the agent with preset null and every field (it keeps its id)." }, { "$ref": "#/components/schemas/AgentPresetRef" } ] }, "reasoning_effort": { "description": "Reasoning effort the agent runs at. Null when its model takes none, or for a version saved before efforts were stored, which runs at the harness default.", "type": [ "string", "null" ] }, "repository_ids": { "description": "The selected repositories of the project (ULIDs), in the order saved.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "signal": { "allOf": [ { "description": "The agent's signal: each review distilled into one reading. It has no name of its own; a Change shows it under the agent's name." }, { "$ref": "#/components/schemas/AgentSignal" } ] }, "timeout_ms": { "description": "Agent process time limit, in milliseconds.", "format": "int64", "type": "integer" }, "triggers": { "description": "Zero or one trigger; empty means the agent only runs when asked to. Push triggers run when the push listener is enabled.", "items": { "$ref": "#/components/schemas/AgentTrigger" }, "type": [ "array", "null" ] }, "version": { "description": "Version number.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "agent_id", "version", "created_at", "created_by", "preset", "is_enabled", "environment_id", "repository_ids", "triggers", "name", "description", "harness", "model", "reasoning_effort", "timeout_ms", "instructions", "signal" ], "type": "object" }, "AllFilterTab": { "additionalProperties": false, "properties": { "displaySettings": { "additionalProperties": { "type": "string" }, "type": "object" }, "filterOrder": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "filters": { "additionalProperties": {}, "type": "object" }, "name": { "type": "string" } }, "required": [ "name", "filters", "filterOrder" ], "type": "object" }, "ApiError": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ApiError.json" ], "format": "uri", "readOnly": true, "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" } }, "required": [ "error" ], "type": "object" }, "ApprovalReviewer": { "additionalProperties": false, "properties": { "actor_account_id": { "type": "string" }, "login": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "reviewed_head_sha": { "type": [ "string", "null" ] }, "state": { "enum": [ "pending", "approved", "stale", "changes_requested", "excluded" ], "type": "string" } }, "required": [ "login", "state", "reviewed_head_sha", "reason" ], "type": "object" }, "AttachmentCompleteResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AttachmentCompleteResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "attachment": { "$ref": "#/components/schemas/AttachmentJSON" } }, "required": [ "attachment" ], "type": "object" }, "AttachmentIntentBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AttachmentIntentBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "contentType": {}, "filename": {}, "height": {}, "width": {} }, "type": "object" }, "AttachmentIntentResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AttachmentIntentResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "id": { "type": "string" }, "upload": { "$ref": "#/components/schemas/UploadInfoJSON" } }, "required": [ "id", "upload" ], "type": "object" }, "AttachmentJSON": { "additionalProperties": false, "properties": { "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "createdByAccountId": { "type": "string" }, "filename": { "type": "string" }, "height": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "type": "string" }, "isReady": { "type": "boolean" }, "kind": { "type": "string" }, "repoId": { "type": "string" }, "sizeBytes": { "format": "int64", "type": "integer" }, "trailId": { "type": "string" }, "width": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "filename", "contentType", "sizeBytes", "isReady", "kind", "createdByAccountId", "createdAt", "trailId", "repoId", "width", "height" ], "type": "object" }, "AttachmentListResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/AttachmentListResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "attachments": { "items": { "$ref": "#/components/schemas/AttachmentJSON" }, "type": [ "array", "null" ] } }, "required": [ "attachments" ], "type": "object" }, "AttributeTypeAndValue": { "additionalProperties": false, "properties": { "Type": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "Value": {} }, "required": [ "Type", "Value" ], "type": "object" }, "AutomationIdentity": { "additionalProperties": false, "properties": { "automation_id": { "description": "The automation's aut_\u003cULID\u003e subject, for an automation that is not a plugin installation.", "type": "string" }, "installation_id": { "description": "The plugin installation's ins_\u003cULID\u003e id.", "type": "string" }, "plugin": { "description": "The plugin's slug.", "type": "string" } }, "type": "object" }, "BillingSubjectRef": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "enum": [ "org", "account" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "BranchCommitDays": { "additionalProperties": false, "properties": { "branch": { "type": "string" }, "days": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "branch", "days" ], "type": "object" }, "BranchesOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/BranchesOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "default_branch": { "type": "string" }, "from_cache": { "type": "boolean" }, "stored_default_branch": { "type": "string" } }, "required": [ "branches", "default_branch", "stored_default_branch", "from_cache" ], "type": "object" }, "BucketItem": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "checkpoints": { "format": "int64", "type": "integer" }, "commits": { "format": "int64", "type": "integer" }, "date": { "type": "string" }, "deletions": { "format": "int64", "type": "integer" }, "input_tokens": { "format": "int64", "type": "integer" }, "output_tokens": { "format": "int64", "type": "integer" } }, "required": [ "date", "commits", "checkpoints", "additions", "deletions", "input_tokens", "output_tokens" ], "type": "object" }, "Certificate": { "additionalProperties": false, "properties": { "AuthorityKeyId": { "contentEncoding": "base64", "type": "string" }, "BasicConstraintsValid": { "type": "boolean" }, "CRLDistributionPoints": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "DNSNames": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "EmailAddresses": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "ExcludedDNSDomains": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "ExcludedEmailAddresses": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "ExcludedIPRanges": { "items": { "$ref": "#/components/schemas/IPNet" }, "type": [ "array", "null" ] }, "ExcludedURIDomains": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "ExtKeyUsage": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "Extensions": { "items": { "$ref": "#/components/schemas/Extension" }, "type": [ "array", "null" ] }, "ExtraExtensions": { "items": { "$ref": "#/components/schemas/Extension" }, "type": [ "array", "null" ] }, "IPAddresses": { "items": { "format": "ipv4", "type": "string" }, "type": [ "array", "null" ] }, "InhibitAnyPolicy": { "format": "int64", "type": "integer" }, "InhibitAnyPolicyZero": { "type": "boolean" }, "InhibitPolicyMapping": { "format": "int64", "type": "integer" }, "InhibitPolicyMappingZero": { "type": "boolean" }, "IsCA": { "type": "boolean" }, "Issuer": { "$ref": "#/components/schemas/Name" }, "IssuingCertificateURL": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "KeyUsage": { "format": "int64", "type": "integer" }, "MaxPathLen": { "format": "int64", "type": "integer" }, "MaxPathLenZero": { "type": "boolean" }, "NotAfter": { "format": "date-time", "type": "string" }, "NotBefore": { "format": "date-time", "type": "string" }, "OCSPServer": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "PermittedDNSDomains": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "PermittedDNSDomainsCritical": { "type": "boolean" }, "PermittedEmailAddresses": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "PermittedIPRanges": { "items": { "$ref": "#/components/schemas/IPNet" }, "type": [ "array", "null" ] }, "PermittedURIDomains": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "Policies": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "PolicyIdentifiers": { "items": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "PolicyMappings": { "items": { "$ref": "#/components/schemas/PolicyMapping" }, "type": [ "array", "null" ] }, "PublicKey": {}, "PublicKeyAlgorithm": { "format": "int64", "type": "integer" }, "Raw": { "contentEncoding": "base64", "type": "string" }, "RawIssuer": { "contentEncoding": "base64", "type": "string" }, "RawSignatureAlgorithm": { "contentEncoding": "base64", "type": "string" }, "RawSubject": { "contentEncoding": "base64", "type": "string" }, "RawSubjectPublicKeyInfo": { "contentEncoding": "base64", "type": "string" }, "RawTBSCertificate": { "contentEncoding": "base64", "type": "string" }, "RequireExplicitPolicy": { "format": "int64", "type": "integer" }, "RequireExplicitPolicyZero": { "type": "boolean" }, "SerialNumber": { "type": [ "string", "null" ] }, "Signature": { "contentEncoding": "base64", "type": "string" }, "SignatureAlgorithm": { "format": "int64", "type": "integer" }, "Subject": { "$ref": "#/components/schemas/Name" }, "SubjectKeyId": { "contentEncoding": "base64", "type": "string" }, "URIs": { "items": { "$ref": "#/components/schemas/URL" }, "type": [ "array", "null" ] }, "UnhandledCriticalExtensions": { "items": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "UnknownExtKeyUsage": { "items": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "Version": { "format": "int64", "type": "integer" } }, "required": [ "Raw", "RawTBSCertificate", "RawSubjectPublicKeyInfo", "RawSubject", "RawIssuer", "RawSignatureAlgorithm", "Signature", "SignatureAlgorithm", "PublicKeyAlgorithm", "PublicKey", "Version", "SerialNumber", "Issuer", "Subject", "NotBefore", "NotAfter", "KeyUsage", "Extensions", "ExtraExtensions", "UnhandledCriticalExtensions", "ExtKeyUsage", "UnknownExtKeyUsage", "BasicConstraintsValid", "IsCA", "MaxPathLen", "MaxPathLenZero", "SubjectKeyId", "AuthorityKeyId", "OCSPServer", "IssuingCertificateURL", "DNSNames", "EmailAddresses", "IPAddresses", "URIs", "PermittedDNSDomainsCritical", "PermittedDNSDomains", "ExcludedDNSDomains", "PermittedIPRanges", "ExcludedIPRanges", "PermittedEmailAddresses", "ExcludedEmailAddresses", "PermittedURIDomains", "ExcludedURIDomains", "CRLDistributionPoints", "PolicyIdentifiers", "Policies", "InhibitAnyPolicy", "InhibitAnyPolicyZero", "InhibitPolicyMapping", "InhibitPolicyMappingZero", "RequireExplicitPolicy", "RequireExplicitPolicyZero", "PolicyMappings" ], "type": "object" }, "ChangeResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ChangeResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "actions": { "allOf": [ { "description": "Availability by operation for this caller and Trail snapshot. The server revalidates every submitted command." }, { "$ref": "#/components/schemas/TrailActions" } ] }, "agents": { "description": "Saved agents with a run on this Change, apart from the repository runners' monitors: each one's latest run, its signal's readings and who it is.", "items": { "$ref": "#/components/schemas/TrailAgentJSON" }, "type": [ "array", "null" ] }, "assignee_identities": { "items": { "$ref": "#/components/schemas/TrailAssigneeIdentity" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailAuthor" }, "base": { "type": "string" }, "base_sha": { "type": [ "string", "null" ] }, "body_document": { "$ref": "#/components/schemas/TrailBodyDocumentJSON" }, "branch": { "type": [ "string", "null" ] }, "branch_state": { "description": "Observed availability of the associated branch. Unknown is not a deletion; original_branch is a historical name, not proof of a live branch.", "enum": [ "present", "deleted", "unlinked", "unknown" ], "type": "string" }, "code_changes": { "description": "Current code evidence: present means commits ahead of base, none means a confirmed zero or an indexed base tip equal to the displayed head when comparison is unavailable, unknown means no usable evidence for a Change that tracks a branch. not_applicable means no live comparison exists (merged, closed or unlinked); terminal history uses frozen snapshot refs.", "enum": [ "present", "none", "unknown", "not_applicable" ], "type": "string" }, "comment_count": { "format": "int64", "type": "integer" }, "config_source": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "deployments": { "allOf": [ { "description": "Deployments at the current or frozen head; display-only, independent of checks and merge gates." }, { "$ref": "#/components/schemas/TrailDeployments" } ] }, "gh_pr_id": { "format": "int64", "type": "integer" }, "has_code_changes": { "type": "boolean" }, "head_sha": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "last_activity_at": { "description": "Latest meaningful activity on the Change; excludes background bookkeeping and falls back to created_at until activity is recorded.", "format": "date-time", "type": "string" }, "lifecycle_sync": { "description": "Pending means linked PR metadata reports a terminal transition not yet applied to this Change, or the linked PR's head branch was deleted. Settled means no such observed transition, not a guarantee that all webhooks have arrived.", "enum": [ "settled", "pending" ], "type": "string" }, "merge_base_sha": { "type": [ "string", "null" ] }, "mergeability": { "$ref": "#/components/schemas/TrailMergeabilityResponse" }, "merged_at": { "format": "date-time", "type": [ "string", "null" ] }, "monitors": { "items": { "$ref": "#/components/schemas/TrailMonitorItemJSON" }, "type": [ "array", "null" ] }, "number": { "format": "int64", "type": "integer" }, "original_branch": { "type": [ "string", "null" ] }, "parent": { "allOf": [ { "description": "Discoverable project parent on list/detail reads; absence does not prove the work is parentless" }, { "$ref": "#/components/schemas/TrailParentReference" } ] }, "phase": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "ready_for_review": { "type": "boolean" }, "repository": { "description": "Repository basename, or empty when display metadata has not resolved", "type": "string" }, "repositoryId": { "type": "string" }, "reviewers": { "items": { "$ref": "#/components/schemas/TrailReviewer" }, "type": [ "array", "null" ] }, "runners": { "items": { "$ref": "#/components/schemas/TrailRunnerItemJSON" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "title": { "type": "string" }, "trailId": { "type": "string" }, "type": { "type": "string" }, "unresolved_count": { "format": "int64", "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "description": "Web app page for this code work; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "trailId", "repositoryId", "repository", "body_document", "monitors", "agents", "runners", "actions", "mergeability", "config_source", "merge_base_sha", "base_sha", "head_sha", "id", "number", "title", "status", "branch", "original_branch", "base", "type", "priority", "author", "assignees", "assignee_identities", "reviewers", "ready_for_review", "has_code_changes", "comment_count", "unresolved_count", "created_at", "updated_at", "merged_at", "last_activity_at", "phase", "branch_state", "code_changes", "lifecycle_sync" ], "type": "object" }, "ChangeSummaryResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ChangeSummaryResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "base": { "type": "string" }, "branch": { "description": "Active head branch; empty when detached", "type": "string" }, "createdAt": { "type": "string" }, "deployments": { "allOf": [ { "description": "Deployment rollup at the Change head; display-only, never affects readiness. Present on project Trail detail and update responses, never on lists." }, { "$ref": "#/components/schemas/DeploymentSummary" } ] }, "ghPrId": { "format": "int64", "type": "integer" }, "hasCodeChanges": { "type": "boolean" }, "id": { "type": "string" }, "lastActivityAt": { "type": "string" }, "number": { "format": "int64", "type": "integer" }, "originalBranch": { "type": "string" }, "repository": { "description": "Repository basename, or empty when display metadata has not resolved", "type": "string" }, "repositoryId": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "repositoryId", "repository", "branch", "originalBranch", "base", "number", "title", "status", "hasCodeChanges", "createdAt", "updatedAt", "lastActivityAt" ], "type": "object" }, "CheckRunOutput": { "additionalProperties": false, "properties": { "summary": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "CheckRunResult": { "additionalProperties": false, "properties": { "check_run": { "$ref": "#/components/schemas/CheckRunResultValue" }, "outcome": { "type": "string" } }, "required": [ "check_run", "outcome" ], "type": "object" }, "CheckRunResultValue": { "additionalProperties": false, "properties": { "conclusion": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "key": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "key", "status", "conclusion" ], "type": "object" }, "CheckRunStep": { "additionalProperties": false, "properties": { "conclusion": { "type": [ "string", "null" ] }, "exit_status": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "status", "conclusion" ], "type": "object" }, "CheckRunWrite": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "type": "string" }, "conclusion": { "type": "string" }, "deadline_at": { "format": "date-time", "type": "string" }, "details_url": { "type": "string" }, "external_id": { "type": "string" }, "external_updated_at": { "format": "date-time", "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "output": { "$ref": "#/components/schemas/CheckRunOutput" }, "started_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" } }, "required": [ "key", "name", "external_id", "status", "external_updated_at" ], "type": "object" }, "CheckRunsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckRunsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "check_runs": { "items": { "$ref": "#/components/schemas/CurrentCheckRun" }, "type": [ "array", "null" ] } }, "required": [ "check_runs" ], "type": "object" }, "CheckRunsWrite": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckRunsWrite.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "Branch name without the refs/heads/ prefix.", "type": "string" }, "check_runs": { "description": "Up to 5000 runs. May be empty or omitted only when check_suite reports status and external_updated_at, with conclusion required for completed status.", "items": { "$ref": "#/components/schemas/CheckRunWrite" }, "type": [ "array", "null" ] }, "check_suite": { "$ref": "#/components/schemas/CheckSuiteWrite" } }, "required": [ "branch", "check_suite" ], "type": "object" }, "CheckRunsWriteResult": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckRunsWriteResult.json" ], "format": "uri", "readOnly": true, "type": "string" }, "check_suite": { "$ref": "#/components/schemas/CheckRunsWriteResultCheckSuiteStruct" }, "results": { "items": { "$ref": "#/components/schemas/CheckRunResult" }, "type": [ "array", "null" ] } }, "required": [ "check_suite", "results" ], "type": "object" }, "CheckRunsWriteResultCheckSuiteStruct": { "additionalProperties": false, "properties": { "external_id": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "id", "key", "external_id" ], "type": "object" }, "CheckSuiteWrite": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "type": "string" }, "conclusion": { "type": "string" }, "details_url": { "type": "string" }, "external_id": { "type": "string" }, "external_updated_at": { "format": "date-time", "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "started_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" } }, "required": [ "key", "name", "external_id" ], "type": "object" }, "CheckSuitesResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckSuitesResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "check_suites": { "items": { "$ref": "#/components/schemas/CurrentCheckSuite" }, "type": [ "array", "null" ] } }, "required": [ "check_suites" ], "type": "object" }, "CheckpointAnalysisBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckpointAnalysisBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "extraction": { "$ref": "#/components/schemas/CheckpointExtraction" }, "failedChunks": { "format": "int64", "type": "integer" }, "incomplete": { "type": "boolean" }, "pipeline_version": { "type": "string" }, "searchableFiles": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "totalFilesChanged": { "format": "int64", "type": "integer" }, "total_transcript_tokens": { "format": "int64", "type": "integer" } }, "required": [ "status" ], "type": "object" }, "CheckpointAttribution": { "additionalProperties": false, "properties": { "agentLines": { "format": "int64", "type": "integer" }, "agentPercentage": { "format": "double", "type": "number" }, "calculatedAt": { "type": "string" }, "humanAdded": { "format": "int64", "type": "integer" }, "humanModified": { "format": "int64", "type": "integer" }, "humanRemoved": { "format": "int64", "type": "integer" }, "totalCommitted": { "format": "int64", "type": "integer" } }, "required": [ "calculatedAt", "agentLines", "humanAdded", "humanModified", "humanRemoved", "totalCommitted", "agentPercentage" ], "type": "object" }, "CheckpointExtraction": { "additionalProperties": false, "properties": { "decision": { "$ref": "#/components/schemas/DecisionSection" }, "investigation": { "$ref": "#/components/schemas/InvestigationSection" }, "labels": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "summary": { "$ref": "#/components/schemas/SummarySection" } }, "required": [ "labels" ], "type": "object" }, "CheckpointInfo": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "agents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "apiCallCount": { "format": "int64", "type": "integer" }, "attribution": { "$ref": "#/components/schemas/CheckpointAttribution" }, "cacheCreationTokens": { "format": "int64", "type": "integer" }, "cacheReadTokens": { "format": "int64", "type": "integer" }, "checkpointId": { "type": "string" }, "checkpointRepoFullName": { "type": [ "string", "null" ] }, "commitAuthor": { "type": "string" }, "commitAuthorAvatarUrl": { "type": "string" }, "commitAuthorUsername": { "type": [ "string", "null" ] }, "commitBody": { "type": [ "string", "null" ] }, "commitDate": { "type": "string" }, "commitMessage": { "type": "string" }, "commitSha": { "type": "string" }, "commitSubject": { "type": "string" }, "createdAt": { "type": "string" }, "deletions": { "format": "int64", "type": "integer" }, "fileStats": { "items": { "$ref": "#/components/schemas/FileStats" }, "type": [ "array", "null" ] }, "filesChanged": { "format": "int64", "type": "integer" }, "filesTouched": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "inputTokens": { "format": "int64", "type": "integer" }, "outputTokens": { "format": "int64", "type": "integer" }, "sessionCount": { "format": "int64", "type": "integer" }, "sessions": { "items": { "$ref": "#/components/schemas/CheckpointSessionInfo" }, "type": [ "array", "null" ] }, "totalSteps": { "format": "int64", "type": "integer" } }, "required": [ "commitSha", "commitMessage", "commitSubject", "commitBody", "commitAuthor", "commitAuthorUsername", "commitDate", "additions", "deletions", "filesChanged", "filesTouched", "fileStats", "checkpointId", "createdAt", "sessions", "sessionCount", "totalSteps", "agents", "inputTokens", "cacheCreationTokens", "cacheReadTokens", "outputTokens", "apiCallCount", "attribution", "checkpointRepoFullName" ], "type": "object" }, "CheckpointItem": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "checkpoint_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "input_tokens": { "format": "int64", "type": "integer" }, "jurisdiction": { "type": "string" }, "output_tokens": { "format": "int64", "type": "integer" }, "repo_id": { "type": "string" }, "session_count": { "format": "int64", "type": "integer" }, "sha": { "type": "string" }, "state": { "type": "string" }, "steps": { "format": "int64", "type": "integer" } }, "required": [ "repo_id", "jurisdiction", "sha", "state", "checkpoint_id", "created_at", "agent", "steps", "session_count", "input_tokens", "output_tokens" ], "type": "object" }, "CheckpointResolveOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckpointResolveOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "checkpoint": { "$ref": "#/components/schemas/CheckpointInfo" }, "checkpoint_id": { "type": "string" }, "default_branch": { "type": [ "string", "null" ] }, "needs_redirect": { "type": "boolean" }, "repo_full_name": { "type": "string" }, "requested_branch": { "type": [ "string", "null" ] }, "suggested_branch": { "type": [ "string", "null" ] } }, "required": [ "checkpoint_id", "branches", "default_branch", "suggested_branch", "needs_redirect", "requested_branch", "checkpoint", "repo_full_name" ], "type": "object" }, "CheckpointSessionAttribution": { "additionalProperties": false, "properties": { "agentLines": { "format": "int64", "type": "integer" }, "agentPercentage": { "format": "double", "type": "number" }, "calculatedAt": { "type": "string" }, "humanAdded": { "format": "int64", "type": "integer" }, "humanModified": { "format": "int64", "type": "integer" }, "humanRemoved": { "format": "int64", "type": "integer" }, "totalCommitted": { "format": "int64", "type": "integer" } }, "required": [ "calculatedAt", "agentLines", "humanAdded", "humanModified", "humanRemoved", "totalCommitted", "agentPercentage" ], "type": "object" }, "CheckpointSessionInfo": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "attribution": { "$ref": "#/components/schemas/CheckpointSessionAttribution" }, "checkpointTranscriptStart": { "format": "int64", "type": "integer" }, "createdAt": { "type": "string" }, "displayName": { "type": "string" }, "kind": { "type": "string" }, "model": { "type": "string" }, "prompt": { "type": [ "string", "null" ] }, "sessionId": { "type": "string" }, "skillEvents": { "items": { "$ref": "#/components/schemas/SkillEvent" }, "type": [ "array", "null" ] }, "steps": { "format": "int64", "type": "integer" }, "tokenUsage": { "$ref": "#/components/schemas/CheckpointSessionTokenUsage" }, "transcriptIdentifierAtStart": { "type": "string" } }, "required": [ "prompt", "agent", "steps" ], "type": "object" }, "CheckpointSessionTokenUsage": { "additionalProperties": false, "properties": { "apiCallCount": { "format": "int64", "type": "integer" }, "cacheCreationTokens": { "format": "int64", "type": "integer" }, "cacheReadTokens": { "format": "int64", "type": "integer" }, "inputTokens": { "format": "int64", "type": "integer" }, "outputTokens": { "format": "int64", "type": "integer" } }, "required": [ "inputTokens", "cacheCreationTokens", "cacheReadTokens", "outputTokens", "apiCallCount" ], "type": "object" }, "CheckpointStatusOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckpointStatusOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "app_has_access": { "type": "boolean" }, "checkpoint_branch_state": { "type": "string" }, "checkpoint_count": { "format": "int64", "type": "integer" }, "checkpoint_repo_full_name": { "type": [ "string", "null" ] }, "session_branch_exists": { "type": "boolean" }, "viewer_can_see_checkpoint_data": { "type": "boolean" } }, "required": [ "app_has_access", "session_branch_exists", "checkpoint_count", "viewer_can_see_checkpoint_data", "checkpoint_branch_state", "checkpoint_repo_full_name" ], "type": "object" }, "CheckpointTranscriptOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckpointTranscriptOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "checkpointId": { "type": "string" }, "from_cache": { "type": "boolean" }, "sessions": { "items": { "$ref": "#/components/schemas/SessionTranscript" }, "type": [ "array", "null" ] }, "status": { "type": "string" } }, "required": [ "status", "checkpointId", "sessions", "from_cache" ], "type": "object" }, "CheckpointsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CheckpointsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "checkpoints": { "items": { "$ref": "#/components/schemas/CheckpointItem" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "streakDates": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "timeframe": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "checkpoints", "streakDates", "timeframe", "updated_at", "meta" ], "type": "object" }, "CodeVersionJSON": { "additionalProperties": false, "properties": { "base_ref": { "type": [ "string", "null" ] }, "base_sha": { "type": [ "string", "null" ] }, "captured_at": { "format": "date-time", "type": "string" }, "head_ref": { "type": [ "string", "null" ] }, "head_sha": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "repo_id": { "type": "string" }, "trail_id": { "type": "string" } }, "required": [ "id", "trail_id", "repo_id", "base_ref", "head_ref", "base_sha", "head_sha", "captured_at" ], "type": "object" }, "CommentLocationJSON": { "additionalProperties": false, "properties": { "code_version_id": { "type": "string" }, "end_column": { "format": "int64", "type": [ "integer", "null" ] }, "end_line": { "format": "int64", "type": [ "integer", "null" ] }, "file_path": { "type": [ "string", "null" ] }, "granularity": { "type": "string" }, "id": { "type": "string" }, "language": { "type": [ "string", "null" ] }, "nearby_text": { "type": [ "string", "null" ] }, "review_comment_id": { "type": "string" }, "selected_text": { "type": [ "string", "null" ] }, "start_column": { "format": "int64", "type": [ "integer", "null" ] }, "start_line": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "review_comment_id", "code_version_id", "granularity", "file_path", "start_line", "start_column", "end_line", "end_column", "selected_text", "nearby_text", "language" ], "type": "object" }, "CommitCheckpointInfo": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": [ "integer", "null" ] }, "agents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "apiCallCount": { "format": "int64", "type": [ "integer", "null" ] }, "attribution": { "$ref": "#/components/schemas/CheckpointAttribution" }, "cacheCreationTokens": { "format": "int64", "type": [ "integer", "null" ] }, "cacheReadTokens": { "format": "int64", "type": [ "integer", "null" ] }, "checkpointId": { "type": "string" }, "checkpointRepoFullName": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "commitAuthorUsername": { "type": [ "string", "null" ] }, "commitBody": { "type": [ "string", "null" ] }, "commitDate": { "type": "string" }, "commitMessage": { "type": "string" }, "commitSha": { "type": "string" }, "commitSubject": { "type": "string" }, "createdAt": { "type": "string" }, "deletions": { "format": "int64", "type": [ "integer", "null" ] }, "fileStats": { "items": { "$ref": "#/components/schemas/FileStats" }, "type": [ "array", "null" ] }, "filesChanged": { "format": "int64", "type": [ "integer", "null" ] }, "filesTouched": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "inputTokens": { "format": "int64", "type": [ "integer", "null" ] }, "outputTokens": { "format": "int64", "type": [ "integer", "null" ] }, "sessionCount": { "format": "int64", "type": "integer" }, "sessions": { "items": { "$ref": "#/components/schemas/CheckpointSessionInfo" }, "type": [ "array", "null" ] }, "totalSteps": { "format": "int64", "type": "integer" } }, "required": [ "commitSha", "commitMessage", "commitSubject", "commitBody", "commitAuthor", "commitAuthorUsername", "commitDate", "additions", "deletions", "filesChanged", "filesTouched", "fileStats", "checkpointId", "createdAt", "sessions", "sessionCount", "totalSteps", "agents", "inputTokens", "cacheCreationTokens", "cacheReadTokens", "outputTokens", "apiCallCount", "attribution", "checkpointRepoFullName" ], "type": "object" }, "CommitDetailOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CommitDetailOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "commit": { "$ref": "#/components/schemas/ResolvedRepoCommit" }, "commit_sha": { "type": "string" }, "default_branch": { "type": [ "string", "null" ] }, "repo_full_name": { "type": "string" }, "suggested_branch": { "type": [ "string", "null" ] } }, "required": [ "commit_sha", "branches", "default_branch", "suggested_branch", "commit", "repo_full_name" ], "type": "object" }, "CommitItem": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "committed_at": { "format": "date-time", "type": "string" }, "deletions": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "has_checkpoint": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "repo_id": { "type": "string" }, "sha": { "type": "string" }, "state": { "type": "string" } }, "required": [ "repo_id", "jurisdiction", "sha", "state", "committed_at", "additions", "deletions", "files_changed", "has_checkpoint" ], "type": "object" }, "CommitRowsResolveInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CommitRowsResolveInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitShas": { "description": "Full commit shas (40- or 64-hex) to resolve; malformed shas are treated as unknown", "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "commitShas" ], "type": "object" }, "CommitRowsResolveOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CommitRowsResolveOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "rows": { "additionalProperties": { "$ref": "#/components/schemas/RepoCommitListItem" }, "type": "object" } }, "required": [ "rows" ], "type": "object" }, "CommitStatDayItem": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "date": { "type": "string" }, "with_checkpoint": { "format": "int64", "type": "integer" } }, "required": [ "date", "count", "with_checkpoint" ], "type": "object" }, "CommitsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CommitsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commits": { "items": { "$ref": "#/components/schemas/CommitItem" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "timeframe": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "commits", "timeframe", "updated_at", "meta" ], "type": "object" }, "CompareCheckpoint": { "additionalProperties": false, "properties": { "agents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "checkpointId": { "type": "string" }, "sessionCount": { "format": "int64", "type": "integer" }, "sessions": { "items": { "$ref": "#/components/schemas/CheckpointSessionInfo" }, "type": "array" } }, "required": [ "checkpointId", "sessionCount", "agents" ], "type": "object" }, "CompareCommitSummary": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": [ "integer", "null" ] }, "checkpoints": { "items": { "$ref": "#/components/schemas/CompareCheckpoint" }, "type": [ "array", "null" ] }, "commitAuthorAvatarUrl": { "type": "string" }, "commitAuthorIdentity": { "$ref": "#/components/schemas/ContributorIdentity" }, "commitAuthorUsername": { "type": [ "string", "null" ] }, "commitBody": { "type": [ "string", "null" ] }, "commitDate": { "type": [ "string", "null" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitSha": { "type": "string" }, "commitSubject": { "type": [ "string", "null" ] }, "deletions": { "format": "int64", "type": [ "integer", "null" ] }, "filesChanged": { "format": "int64", "type": [ "integer", "null" ] }, "stats_pending": { "type": "boolean" } }, "required": [ "commitSha", "commitMessage", "commitSubject", "commitBody", "commitAuthorUsername", "commitDate", "additions", "deletions", "filesChanged", "stats_pending", "checkpoints" ], "type": "object" }, "CompareContributor": { "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "commitCount": { "format": "int64", "type": "integer" }, "githubId": { "format": "int64", "type": [ "integer", "null" ] }, "username": { "type": "string" } }, "required": [ "username", "accountId", "githubId", "commitCount" ], "type": "object" }, "CompareContributorsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CompareContributorsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "contributors": { "items": { "$ref": "#/components/schemas/CompareContributor" }, "type": [ "array", "null" ] } }, "required": [ "contributors" ], "type": "object" }, "CompareOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/CompareOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "ahead_by": { "format": "int64", "type": "integer" }, "base": { "type": "string" }, "behind_by": { "format": "int64", "type": "integer" }, "commits": { "items": { "$ref": "#/components/schemas/CompareCommitSummary" }, "type": [ "array", "null" ] }, "compare_kind": { "type": "string" }, "head": { "type": "string" }, "limit": { "format": "int64", "type": "integer" }, "offset": { "format": "int64", "type": "integer" }, "source": { "type": "string" } }, "required": [ "base", "head", "compare_kind", "source", "ahead_by", "behind_by", "commits", "limit", "offset" ], "type": "object" }, "ConfigActor": { "additionalProperties": false, "properties": { "id": { "description": "Full principal id: an account ULID, svc_\u003cULID\u003e for a service account, or aut_\u003cULID\u003e for an automation.", "type": "string" }, "kind": { "description": "Open principal kind; currently account, service_account, or automation. Clients must tolerate future values.", "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "ConfigArchive": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigArchive.json" ], "format": "uri", "readOnly": true, "type": "string" } }, "type": "object" }, "ConfigPageAgent": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageAgent.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/Agent" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ConfigPageAgentPreset": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageAgentPreset.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/AgentPreset" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ConfigPageAgentVersion": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageAgentVersion.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/AgentVersion" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ConfigPageEnvironment": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageEnvironment.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/Environment" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ConfigPageEnvironmentVersion": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageEnvironmentVersion.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/EnvironmentVersion" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ConfigPageRepositoryRun": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageRepositoryRun.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/RepositoryRun" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ConfigPageRunSummary": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ConfigPageRunSummary.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/RunSummary" }, "type": [ "array", "null" ] }, "next_cursor": { "description": "Pass as cursor to fetch the next page; omitted on the last page.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "ContributorAgentsItem": { "additionalProperties": false, "properties": { "account_id": { "type": [ "string", "null" ] }, "additions": { "format": "int64", "type": "integer" }, "agents": { "additionalProperties": { "format": "int64", "type": "integer" }, "type": "object" }, "deletions": { "format": "int64", "type": "integer" }, "github_id": { "format": "int64", "type": [ "integer", "null" ] }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "total_commits": { "format": "int64", "type": "integer" }, "untracked": { "format": "int64", "type": "integer" }, "username": { "type": [ "string", "null" ] } }, "required": [ "username", "github_id", "account_id", "total_commits", "additions", "deletions", "agents", "untracked", "identity" ], "type": "object" }, "ContributorIdentity": { "additionalProperties": false, "properties": { "account_id": { "type": [ "string", "null" ] }, "automation": { "$ref": "#/components/schemas/AutomationIdentity" }, "avatar_url": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "handles": { "items": { "$ref": "#/components/schemas/IdentityHandle" }, "type": [ "array", "null" ] }, "kind": { "type": "string" }, "username": { "type": "string" } }, "required": [ "kind", "account_id", "display_name", "avatar_url", "handles" ], "type": "object" }, "ContributorItem": { "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "active_days": { "format": "int64", "type": "integer" }, "additions": { "format": "int64", "type": "integer" }, "checkpoints": { "format": "int64", "type": "integer" }, "commits": { "format": "int64", "type": "integer" }, "deletions": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "input_tokens": { "format": "int64", "type": "integer" }, "last_active": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "output_tokens": { "format": "int64", "type": "integer" }, "steps": { "format": "int64", "type": "integer" } }, "required": [ "commits", "checkpoints", "additions", "deletions", "files_changed", "input_tokens", "output_tokens", "steps", "active_days", "last_active" ], "type": "object" }, "ContributorTokenItem": { "additionalProperties": false, "properties": { "account_id": { "type": [ "string", "null" ] }, "github_id": { "format": "int64", "type": [ "integer", "null" ] }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "input_tokens": { "format": "double", "type": "number" }, "output_tokens": { "format": "double", "type": "number" }, "username": { "type": [ "string", "null" ] } }, "required": [ "username", "github_id", "account_id", "input_tokens", "output_tokens", "identity" ], "type": "object" }, "ContributorsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ContributorsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "contributors": { "items": { "$ref": "#/components/schemas/ContributorItem" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "timeframe": { "type": "string" } }, "required": [ "contributors", "timeframe", "meta" ], "type": "object" }, "CurrentCheckRun": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "conclusion": { "type": [ "string", "null" ] }, "deadline_at": { "format": "date-time", "type": [ "string", "null" ] }, "details_url": { "type": "string" }, "external_id": { "type": "string" }, "external_updated_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "output": { "$ref": "#/components/schemas/CheckRunOutput" }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": "string" }, "suite_id": { "type": "string" }, "suite_key": { "type": "string" } }, "required": [ "id", "suite_id", "suite_key", "key", "name", "external_id", "status", "conclusion", "external_updated_at", "started_at", "completed_at", "deadline_at", "details_url", "output" ], "type": "object" }, "CurrentCheckSuite": { "additionalProperties": false, "properties": { "conclusion": { "type": [ "string", "null" ] }, "details_url": { "type": "string" }, "external_id": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "key", "name", "external_id", "details_url", "status", "conclusion" ], "type": "object" }, "DecisionSection": { "additionalProperties": false, "properties": { "accepted": { "type": "string" }, "narrative": { "type": "string" }, "reasoning": { "type": "string" }, "rejected": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "title": { "type": "string" } }, "required": [ "title", "narrative" ], "type": "object" }, "DeploymentGroup": { "additionalProperties": false, "properties": { "key": { "maxLength": 255, "type": "string" }, "name": { "maxLength": 255, "type": "string" } }, "required": [ "key", "name" ], "type": "object" }, "DeploymentSummary": { "additionalProperties": false, "properties": { "availability": { "description": "available: read succeeded (possibly empty). unavailable: the read failed; not zero deployments. not_applicable: no head SHA.", "enum": [ "available", "unavailable", "not_applicable" ], "type": "string" }, "ready": { "description": "Resources completed with conclusion success.", "format": "int64", "type": "integer" }, "total": { "description": "Resources that can become ready: skipped and inactive ones are excluded, so ready can reach total.", "format": "int64", "type": "integer" } }, "required": [ "availability", "ready", "total" ], "type": "object" }, "DiffViewPreference": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiffViewPreference.json" ], "format": "uri", "readOnly": true, "type": "string" }, "fileTreeOpen": { "type": "boolean" }, "viewMode": { "enum": [ "unified", "split" ], "type": "string" }, "wrapLines": { "type": "boolean" } }, "required": [ "viewMode", "wrapLines", "fileTreeOpen" ], "type": "object" }, "DiffViewResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiffViewResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "fileTreeOpen": { "type": [ "boolean", "null" ] }, "viewMode": { "type": [ "string", "null" ] }, "wrapLines": { "type": [ "boolean", "null" ] } }, "required": [ "viewMode", "wrapLines", "fileTreeOpen" ], "type": "object" }, "DiscoveryDocument": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiscoveryDocument.json" ], "format": "uri", "readOnly": true, "type": "string" }, "claims_supported": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "id_token_signing_alg_values_supported": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "issuer": { "type": "string" }, "jwks_uri": { "type": "string" }, "response_types_supported": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "subject_types_supported": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "issuer", "jwks_uri", "response_types_supported", "subject_types_supported", "id_token_signing_alg_values_supported", "claims_supported" ], "type": "object" }, "DiscussionCreateResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiscussionCreateResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "discussion": { "$ref": "#/components/schemas/DiscussionSummaryJSON" }, "message": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" } }, "required": [ "discussion", "message" ], "type": "object" }, "DiscussionDetailResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiscussionDetailResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "discussion": { "$ref": "#/components/schemas/DiscussionSummaryJSON" }, "eventCursor": { "type": "string" }, "messages": { "items": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" }, "type": [ "array", "null" ] } }, "required": [ "discussion", "messages", "eventCursor" ], "type": "object" }, "DiscussionEventJSON": { "additionalProperties": false, "properties": { "actorId": { "type": "string" }, "createdAt": { "type": "string" }, "discussionId": { "type": [ "string", "null" ] }, "eventType": { "type": "string" }, "id": { "type": "string" }, "payload": {}, "targetId": { "type": "string" }, "trailId": { "type": "string" } }, "required": [ "id", "trailId", "discussionId", "actorId", "eventType", "targetId", "payload", "createdAt" ], "type": "object" }, "DiscussionEventsResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiscussionEventsResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/DiscussionEventJSON" }, "type": [ "array", "null" ] } }, "required": [ "events" ], "type": "object" }, "DiscussionSummaryJSON": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": [ "string", "null" ] }, "created_by_identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "etag": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "last_message_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_message_author": { "type": [ "string", "null" ] }, "message_count": { "format": "int64", "type": "integer" }, "messages": { "description": "Only on the list route with include_messages=true", "items": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" }, "type": "array" }, "participants": { "items": { "$ref": "#/components/schemas/TrailDiscussionParticipantJSON" }, "type": [ "array", "null" ] }, "resolved": { "type": "boolean" }, "resolved_at": { "format": "date-time", "type": [ "string", "null" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_by_identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "review_comment": { "$ref": "#/components/schemas/ReviewCommentJSON" }, "review_comment_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "trail_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "trail_id", "title", "kind", "resolved", "resolved_by", "resolved_by_identity", "resolved_at", "created_by", "created_by_identity", "created_at", "updated_at", "last_message_at", "last_message_author", "message_count", "participants", "review_comment_id", "review_comment" ], "type": "object" }, "DiscussionUpdateResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiscussionUpdateResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "discussion": { "$ref": "#/components/schemas/DiscussionSummaryJSON" } }, "required": [ "discussion" ], "type": "object" }, "DiscussionsListResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DiscussionsListResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "eventCursor": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/DiscussionSummaryJSON" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": [ "string", "null" ] } }, "required": [ "items", "nextPageToken", "eventCursor" ], "type": "object" }, "DismissInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DismissInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "key": { "maxLength": 200, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*(?::[A-Za-z0-9_-]+)?$", "type": "string" } }, "required": [ "key" ], "type": "object" }, "Dismissal": { "additionalProperties": false, "properties": { "dismissed_at": { "format": "date-time", "type": "string" }, "key": { "description": "The dismissed notice, optionally scoped after a colon.", "type": "string" } }, "required": [ "key", "dismissed_at" ], "type": "object" }, "DismissalPreferences": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DismissalPreferences.json" ], "format": "uri", "readOnly": true, "type": "string" }, "dismissals": { "description": "Dismissed notices, oldest first.", "items": { "$ref": "#/components/schemas/Dismissal" }, "type": [ "array", "null" ] } }, "required": [ "dismissals" ], "type": "object" }, "DispatchBulletWire": { "additionalProperties": false, "properties": { "branch": { "type": "string" }, "checkpointId": { "type": "string" }, "createdAt": { "type": "string" }, "labels": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "source": { "type": "string" }, "text": { "type": "string" } }, "required": [ "checkpointId", "text", "source", "branch", "createdAt", "labels" ], "type": "object" }, "DispatchDetailWire": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DispatchDetailWire.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "coveredRepoGithubIds": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "coveredRepoOrigins": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "coveredRepoUlids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "coveredRepos": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "errorMessage": { "type": [ "string", "null" ] }, "generatedMarkdown": { "type": "string" }, "id": { "type": "string" }, "isPersisted": { "type": "boolean" }, "repos": { "items": { "$ref": "#/components/schemas/DispatchRepoGroupWire" }, "type": [ "array", "null" ] }, "setupId": { "type": "string" }, "status": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "totals": { "$ref": "#/components/schemas/DispatchTotalsWire" }, "updatedAt": { "format": "date-time", "type": "string" }, "voice": { "type": [ "string", "null" ] }, "window": { "$ref": "#/components/schemas/DispatchWindowWire" } }, "required": [ "id", "setupId", "status", "title", "coveredRepos", "coveredRepoUlids", "coveredRepoOrigins", "coveredRepoGithubIds", "branches", "voice", "window", "totals", "repos", "generatedMarkdown", "isPersisted", "errorMessage", "createdAt", "updatedAt", "completedAt" ], "type": "object" }, "DispatchGenerateInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DispatchGenerateInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "description": "Branch names (max 5); omitted selects each repo's default branch. The legacy \"all\" sentinel is rejected." }, "orgs": { "description": "Org scopes; not currently supported (400).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "repos": { "description": "Repos to cover (1-5), each gh/owner/repo or et/owner/repo.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "since": { "description": "ISO-8601 timestamp or relative token (e.g. \"7d\").", "type": "string" }, "until": { "description": "ISO-8601 timestamp or relative token.", "type": "string" }, "voice": { "description": "Voice preference text (max 1000 chars), or a preset name (neutral, marvin).", "type": "string" } }, "type": "object" }, "DispatchRepoGroupWire": { "additionalProperties": false, "properties": { "fullName": { "type": "string" }, "sections": { "items": { "$ref": "#/components/schemas/DispatchSectionWire" }, "type": [ "array", "null" ] } }, "required": [ "fullName", "sections" ], "type": "object" }, "DispatchRunListOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DispatchRunListOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/DispatchSummaryWire" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": [ "string", "null" ] } }, "required": [ "items", "nextPageToken" ], "type": "object" }, "DispatchSectionWire": { "additionalProperties": false, "properties": { "bullets": { "items": { "$ref": "#/components/schemas/DispatchBulletWire" }, "type": [ "array", "null" ] }, "label": { "type": "string" } }, "required": [ "label", "bullets" ], "type": "object" }, "DispatchSetupListOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DispatchSetupListOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/DispatchSetupWire" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": [ "string", "null" ] } }, "required": [ "items", "nextPageToken" ], "type": "object" }, "DispatchSetupPatchInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DispatchSetupPatchInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "isPinned": { "type": "boolean" }, "name": { "description": "New display name (max 120 chars); null clears it.", "type": "string" } }, "type": "object" }, "DispatchSetupWire": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/DispatchSetupWire.json" ], "format": "uri", "readOnly": true, "type": "string" }, "config": { "additionalProperties": {}, "type": "object" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "isPinned": { "type": "boolean" }, "lastDispatchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "recentDispatches": { "items": { "$ref": "#/components/schemas/DispatchSummaryWire" }, "type": [ "array", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "isPinned", "config", "lastDispatchedAt", "createdAt", "updatedAt", "recentDispatches" ], "type": "object" }, "DispatchSummaryWire": { "additionalProperties": false, "properties": { "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "coveredRepoGithubIds": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "coveredRepoOrigins": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "coveredRepoUlids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "coveredRepos": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "setupId": { "type": "string" }, "status": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "voice": { "type": [ "string", "null" ] }, "voiceBucket": { "type": [ "string", "null" ] }, "windowSince": { "type": [ "string", "null" ] }, "windowUntil": { "type": [ "string", "null" ] } }, "required": [ "id", "setupId", "status", "title", "coveredRepos", "coveredRepoUlids", "coveredRepoOrigins", "coveredRepoGithubIds", "windowSince", "windowUntil", "voice", "voiceBucket", "createdAt", "updatedAt", "completedAt" ], "type": "object" }, "DispatchTotalsWire": { "additionalProperties": false, "properties": { "branches": { "format": "int64", "type": "integer" }, "checkpoints": { "format": "int64", "type": "integer" }, "filesTouched": { "format": "int64", "type": "integer" }, "usedCheckpointCount": { "format": "int64", "type": "integer" } }, "required": [ "checkpoints", "usedCheckpointCount", "branches", "filesTouched" ], "type": "object" }, "DispatchWindowWire": { "additionalProperties": false, "properties": { "firstCheckpointCreatedAt": { "type": [ "string", "null" ] }, "lastCheckpointCreatedAt": { "type": [ "string", "null" ] }, "normalizedSince": { "type": "string" }, "normalizedUntil": { "type": "string" } }, "required": [ "normalizedSince", "normalizedUntil", "firstCheckpointCreatedAt", "lastCheckpointCreatedAt" ], "type": "object" }, "EditorContentPutBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EditorContentPutBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "contentJson": { "description": "Replacement editor-document content (ProseMirror JSON). Required." }, "onlyIfEmpty": { "description": "Apply only while the document is structurally empty: every node is the top doc node or a paragraph (any number of blank paragraphs, or an empty content array, still counts as empty), and no text node holds non-whitespace text. Any other node type — horizontalRule, taskList/taskItem, codeBlock, blockquote, attachmentImage, heading, bulletList/orderedList, hardBreak, … — counts as content even when it renders no visible text of its own. A document that already has content is a 200 no-op, not an error: see the response's isApplied/reason. This is not concurrency control — combine it with If-Match if you need both.", "type": "boolean" }, "schemaVersion": { "description": "Editor schema version; only 1 is supported.", "format": "int64", "type": "integer" }, "updatedByAccountId": { "description": "Account (ULID) the write is attributed to. Exactly one of updatedByAccountId/updatedByActorRef is required.", "type": "string" }, "updatedByActorRef": { "description": "Non-account actor (e.g. an automation principal) the write is attributed to. Exactly one of updatedByAccountId/updatedByActorRef is required.", "type": "string" } }, "required": [ "contentJson" ], "type": "object" }, "EditorContentPutResponseJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EditorContentPutResponseJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "contentJson": {}, "documentKey": { "type": "string" }, "id": { "type": "string" }, "isApplied": { "description": "Whether this write replaced the document's content.", "type": "boolean" }, "reason": { "description": "Set when isApplied is false; currently: document_not_empty.", "type": "string" }, "schemaVersion": { "format": "int64", "type": "integer" }, "updatedAt": { "type": "string" }, "yjsState": { "contentEncoding": "base64", "description": "Encoded Yjs document state (base64).", "type": "string" }, "yjsUpdatedAt": { "type": "string" } }, "required": [ "isApplied", "id", "documentKey", "schemaVersion", "contentJson", "updatedAt" ], "type": "object" }, "EditorDocumentIdentityJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EditorDocumentIdentityJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "document_key": { "type": "string" }, "id": { "type": "string" }, "jurisdiction": { "type": "string" }, "primary_processing_cell": { "type": "string" }, "project_id": { "type": "string" } }, "required": [ "id", "document_key", "project_id", "jurisdiction", "primary_processing_cell" ], "type": "object" }, "EditorSyncDocumentJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EditorSyncDocumentJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "contentJson": {}, "documentKey": { "type": "string" }, "id": { "type": "string" }, "schemaVersion": { "format": "int64", "type": "integer" }, "updatedAt": { "type": "string" }, "yjsState": { "contentEncoding": "base64", "description": "Encoded Yjs document state (base64).", "type": "string" }, "yjsUpdatedAt": { "type": "string" } }, "required": [ "id", "documentKey", "schemaVersion", "contentJson", "updatedAt" ], "type": "object" }, "EditorUpdatePostBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EditorUpdatePostBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "schemaVersion": { "description": "Editor schema version; only 1 is supported.", "format": "int64", "type": "integer" }, "update": { "contentEncoding": "base64", "description": "Yjs update to merge (base64). Required.", "type": "string" }, "updatedByAccountId": { "description": "Account (ULID) the merge is attributed to. Exactly one of updatedByAccountId/updatedByActorRef is required.", "type": "string" }, "updatedByActorRef": { "description": "Non-account actor (e.g. an automation principal) the merge is attributed to. Exactly one of updatedByAccountId/updatedByActorRef is required.", "type": "string" } }, "required": [ "update" ], "type": "object" }, "Environment": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/Environment.json" ], "format": "uri", "readOnly": true, "type": "string" }, "archived_at": { "description": "When the environment was archived; null while active.", "format": "date-time", "type": [ "string", "null" ] }, "archived_by": { "allOf": [ { "description": "Who archived the environment; present only once archived." }, { "$ref": "#/components/schemas/ConfigActor" } ] }, "auto_stop_minutes": { "description": "Sandbox lifetime in minutes, as the provider interprets it; null uses the cell default for the provider.", "format": "int64", "type": [ "integer", "null" ] }, "created_at": { "description": "When version 1 was saved.", "format": "date-time", "type": "string" }, "created_by": { "allOf": [ { "description": "Who saved version 1; each version records its own author." }, { "$ref": "#/components/schemas/ConfigActor" } ] }, "description": { "description": "Free-form description; empty when unset.", "type": "string" }, "etag": { "description": "Write token. Copy this JSON value unchanged into If-Match when replacing or archiving. Prefer it to the HTTP ETag header, which intermediaries may transform.", "type": "string" }, "id": { "description": "Environment id (ULID); stable across versions.", "type": "string" }, "name": { "description": "Display name.", "type": "string" }, "project_id": { "description": "Owning project id (ULID). The environment is reusable across the project's repositories.", "type": "string" }, "updated_at": { "description": "When the last version was saved or the environment was archived.", "format": "date-time", "type": "string" }, "version": { "description": "Current version.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "id", "project_id", "version", "etag", "created_at", "created_by", "updated_at", "archived_at", "name", "description", "auto_stop_minutes" ], "type": "object" }, "EnvironmentCreate": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EnvironmentCreate.json" ], "format": "uri", "readOnly": true, "type": "string" }, "auto_stop_minutes": { "description": "Sandbox lifetime in minutes (Daytona: idle time; E2B: initial wall-clock lifetime, renewed while in use). Omit or send null for the cell default.", "format": "int64", "maximum": 60, "minimum": 1, "type": [ "integer", "null" ] }, "description": { "description": "Free-form description.", "maxLength": 1024, "type": "string" }, "name": { "description": "Display name, without surrounding whitespace.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "EnvironmentFieldsInput": { "additionalProperties": false, "properties": { "auto_stop_minutes": { "description": "Sandbox lifetime in minutes (Daytona: idle time; E2B: initial wall-clock lifetime, renewed while in use). Omit or send null for the cell default.", "format": "int64", "maximum": 60, "minimum": 1, "type": [ "integer", "null" ] }, "description": { "description": "Free-form description.", "maxLength": 1024, "type": "string" }, "name": { "description": "Display name, without surrounding whitespace.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "EnvironmentReplace": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EnvironmentReplace.json" ], "format": "uri", "readOnly": true, "type": "string" }, "auto_stop_minutes": { "description": "Sandbox lifetime in minutes (Daytona: idle time; E2B: initial wall-clock lifetime, renewed while in use). Omit or send null for the cell default.", "format": "int64", "maximum": 60, "minimum": 1, "type": [ "integer", "null" ] }, "description": { "description": "Free-form description.", "maxLength": 1024, "type": "string" }, "name": { "description": "Display name, without surrounding whitespace.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "EnvironmentVersion": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/EnvironmentVersion.json" ], "format": "uri", "readOnly": true, "type": "string" }, "auto_stop_minutes": { "description": "Sandbox lifetime in minutes, as the provider interprets it; null uses the cell default for the provider.", "format": "int64", "type": [ "integer", "null" ] }, "created_at": { "description": "When this version was saved.", "format": "date-time", "type": "string" }, "created_by": { "allOf": [ { "description": "Who saved this version." }, { "$ref": "#/components/schemas/ConfigActor" } ] }, "description": { "description": "Free-form description; empty when unset.", "type": "string" }, "environment_id": { "description": "Environment id (ULID) this version belongs to.", "type": "string" }, "name": { "description": "Display name.", "type": "string" }, "version": { "description": "Version number.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "environment_id", "version", "created_at", "created_by", "name", "description", "auto_stop_minutes" ], "type": "object" }, "ExpertsEvidenceItem": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "attribution_agent_lines": { "format": "int64", "type": "integer" }, "attribution_total_committed": { "format": "int64", "type": "integer" }, "checkpoint_count": { "format": "int64", "type": "integer" }, "checkpoint_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "display_name": { "type": "string" }, "exact_file_matches": { "format": "int64", "type": "integer" }, "last_activity_at": { "type": "string" }, "matched_files": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "model": { "type": "string" }, "prefix_file_matches": { "format": "int64", "type": "integer" }, "session_id": { "type": "string" }, "step_count": { "format": "int64", "type": "integer" } }, "required": [ "session_id", "display_name", "agent", "model", "last_activity_at", "checkpoint_count", "step_count", "matched_files", "exact_file_matches", "prefix_file_matches", "checkpoint_ids" ], "type": "object" }, "ExpertsFacet": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "name": { "type": "string" } }, "required": [ "name", "count" ], "type": "object" }, "ExpertsInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ExpertsInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "Restrict to checkpoints linked on this branch.", "type": "string" }, "evidence_limit": { "description": "Max evidence sessions per profile (1-5, default 3).", "format": "int64", "maximum": 5, "type": "integer" }, "limit": { "description": "Max profiles (1-20, default 8).", "format": "int64", "maximum": 20, "type": "integer" }, "query": { "description": "Natural-language topic (requires code search). Provide scopes OR query.", "type": "string" }, "scopes": { "description": "Path scopes (a file or a directory prefix). Provide scopes OR query.", "items": { "type": "string" }, "maxItems": 25, "type": [ "array", "null" ] } }, "type": "object" }, "ExpertsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ExpertsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "profiles": { "items": { "$ref": "#/components/schemas/ExpertsProfileItem" }, "type": [ "array", "null" ] }, "query": { "type": [ "string", "null" ] }, "repo_full_name": { "type": "string" }, "scopes": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "source": { "type": "string" } }, "required": [ "repo_full_name", "scopes", "query", "branch", "source", "profiles" ], "type": "object" }, "ExpertsProfileItem": { "additionalProperties": false, "properties": { "agent_id": { "type": "string" }, "agent_label": { "type": "string" }, "attribution_agent_lines": { "format": "int64", "type": [ "integer", "null" ] }, "attribution_total_committed": { "format": "int64", "type": [ "integer", "null" ] }, "checkpoint_count": { "format": "int64", "type": "integer" }, "exact_file_matches": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "labels": { "items": { "$ref": "#/components/schemas/ExpertsFacet" }, "type": [ "array", "null" ] }, "last_activity_at": { "type": "string" }, "matched_files": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "mcp_servers": { "items": { "$ref": "#/components/schemas/ExpertsFacet" }, "type": [ "array", "null" ] }, "models": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "prefix_file_matches": { "format": "int64", "type": "integer" }, "raw_agents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "session_count": { "format": "int64", "type": "integer" }, "sessions": { "items": { "$ref": "#/components/schemas/ExpertsEvidenceItem" }, "type": [ "array", "null" ] }, "skills": { "items": { "$ref": "#/components/schemas/ExpertsFacet" }, "type": [ "array", "null" ] }, "step_count": { "format": "int64", "type": "integer" }, "tool_mix": { "items": { "$ref": "#/components/schemas/ExpertsFacet" }, "type": [ "array", "null" ] }, "transcript_tokens": { "format": "int64", "type": "integer" } }, "required": [ "agent_id", "agent_label", "raw_agents", "models", "labels", "skills", "tool_mix", "mcp_servers", "transcript_tokens", "files_changed", "last_activity_at", "session_count", "checkpoint_count", "step_count", "attribution_agent_lines", "attribution_total_committed", "matched_files", "exact_file_matches", "prefix_file_matches", "sessions" ], "type": "object" }, "Extension": { "additionalProperties": false, "properties": { "Critical": { "type": "boolean" }, "Id": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "Value": { "contentEncoding": "base64", "type": "string" } }, "required": [ "Id", "Critical", "Value" ], "type": "object" }, "FavoriteProjectInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/FavoriteProjectInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "project_id": { "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" } }, "required": [ "project_id" ], "type": "object" }, "FileStats": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "deletions": { "format": "int64", "type": "integer" }, "filename": { "type": "string" }, "patch": { "type": "string" }, "patchTruncated": { "type": "boolean" }, "previousFilename": { "type": "string" }, "status": { "type": "string" } }, "required": [ "filename", "status", "additions", "deletions" ], "type": "object" }, "FilterTabsPutBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/FilterTabsPutBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "all_tab": { "$ref": "#/components/schemas/AllFilterTab" }, "saved_tabs": { "items": { "$ref": "#/components/schemas/SavedFilterTab" }, "maxItems": 100, "type": "array" }, "storage_key": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "storage_key" ], "type": "object" }, "FilterTabsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/FilterTabsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "tabs": { "additionalProperties": { "$ref": "#/components/schemas/FilterTabsSlice" }, "type": "object" } }, "required": [ "tabs" ], "type": "object" }, "FilterTabsSlice": { "additionalProperties": false, "properties": { "allTab": { "$ref": "#/components/schemas/AllFilterTab" }, "savedTabs": { "items": { "$ref": "#/components/schemas/SavedFilterTab" }, "type": [ "array", "null" ] } }, "required": [ "savedTabs", "allTab" ], "type": "object" }, "FindingVerdictJSON": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "evidence": { "description": "Where the agent looked at the head it reviewed, and what it found.", "type": "string" }, "outcome": { "description": "resolved or dismissed: the agent closed the finding; awaiting_confirmation: a high severity finding stays open until a person closes it; reopened_by_person, already_closed: a person's decision stood; kept: still present.", "enum": [ "resolved", "dismissed", "kept", "awaiting_confirmation", "reopened_by_person", "already_closed" ], "type": "string" }, "run_id": { "description": "The run that gave it (GET .../runs/{id}).", "type": "string" }, "verdict": { "enum": [ "fixed", "still_present", "no_longer_applies" ], "type": "string" } }, "required": [ "run_id", "verdict", "evidence", "outcome", "created_at" ], "type": "object" }, "ForgeMergeBlockJSON": { "additionalProperties": false, "properties": { "reason": { "description": "Open set: review_required means GitHub needs an approving review; changes_requested means a GitHub reviewer requested changes; checks_pending means a required check on headSha has not finished; blocked means GitHub reports the merge as blocked without naming a readable rule. Unknown future values must be tolerated.", "type": "string", "x-open-enum": [ "review_required", "changes_requested", "checks_pending", "blocked" ] }, "required_approving_review_count": { "description": "Approving reviews GitHub requires; 0 when GitHub did not say.", "format": "int64", "type": "integer" } }, "required": [ "reason", "required_approving_review_count" ], "type": "object" }, "GateDefinition": { "additionalProperties": false, "properties": { "blocking": { "type": "boolean" }, "config": {}, "createdAt": { "format": "date-time", "type": "string" }, "createdBy": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "gateKey": { "type": "string" }, "gateType": { "type": "string" }, "id": { "type": "string" }, "repoId": { "type": "string" }, "scopeId": { "type": [ "string", "null" ] }, "scopeType": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "updatedBy": { "type": [ "string", "null" ] } }, "required": [ "id", "repoId", "scopeType", "scopeId", "gateKey", "gateType", "blocking", "enabled", "config", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "type": "object" }, "GateDefinitionCreateBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GateDefinitionCreateBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "blocking": { "type": "boolean" }, "config": {}, "enabled": { "type": "boolean" }, "gateKey": { "type": "string" }, "gateType": { "type": "string" } }, "required": [ "gateType" ], "type": "object" }, "GateDefinitionCreateOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GateDefinitionCreateOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "gate": { "$ref": "#/components/schemas/GateDefinition" } }, "required": [ "gate" ], "type": "object" }, "GateDefinitionOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GateDefinitionOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "gate": { "$ref": "#/components/schemas/GateDefinition" } }, "required": [ "gate" ], "type": "object" }, "GateDefinitionPatchBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GateDefinitionPatchBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "blocking": { "type": "boolean" }, "config": {}, "enabled": { "type": "boolean" } }, "type": "object" }, "GateResult": { "additionalProperties": false, "properties": { "blocking": { "type": "boolean" }, "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "evaluated_at_sha": { "type": [ "string", "null" ] }, "finding_count": { "format": "int64", "type": [ "integer", "null" ] }, "gate_definition_id": { "type": "string" }, "gate_key": { "type": "string" }, "gate_type": { "type": "string" }, "head_sha": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "not_applicable_reason": { "description": "Machine-readable reason for a not_applicable gate. no_changes means the branch has no changes from its base; it is not an evaluated skipped verdict. Absent for other results, including disabled gates.", "enum": [ "no_changes" ], "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "rationale": { "type": [ "string", "null" ] }, "reviewers": { "items": { "$ref": "#/components/schemas/ApprovalReviewer" }, "type": "array" }, "runner_ids": { "description": "Sorted unique runner IDs contributing to this gate, drawn from the Trail detail runners array. Empty when none are associated or configuration is unavailable.", "items": { "type": "string" }, "type": "array", "uniqueItems": true }, "stale_reason": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "status": { "type": "string" }, "value": {} }, "required": [ "reviewers", "runner_ids", "id", "gate_definition_id", "gate_key", "gate_type", "blocking", "status", "head_sha", "value", "rationale", "created_at", "completed_at", "outcome", "stale_reason", "evaluated_at_sha", "finding_count" ], "type": "object" }, "GateSettingsPatchBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GateSettingsPatchBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "autoMergePolicy": { "type": "string" }, "bypassPolicy": { "type": "string" }, "deleteBranchOnMerge": { "description": "Applies to native (entiredb-hosted) Trails only: GitHub-backed Trails merge through GitHub, whose own auto-delete setting applies.", "type": "boolean" }, "forgeCheckRunEnabled": { "type": "boolean" } }, "type": "object" }, "GateSettingsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GateSettingsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "autoMergePolicy": { "type": "string" }, "bypassPolicy": { "type": "string" }, "deleteBranchOnMerge": { "description": "Whether merging a native Trail deletes its working branch by default. Applies to native (entiredb-hosted) Trails only: GitHub-backed Trails merge through GitHub, whose own auto-delete setting applies.", "type": "boolean" }, "forgeCheckRunEnabled": { "type": "boolean" } }, "required": [ "bypassPolicy", "autoMergePolicy", "forgeCheckRunEnabled", "deleteBranchOnMerge" ], "type": "object" }, "GlobalProjectTrailFacetBucketResponse": { "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "avatarUrl": { "type": "string" }, "count": { "description": "Trails selected by this value; assignee buckets can overlap", "format": "int64", "type": "integer" }, "label": { "description": "Core display name when available, otherwise GitHub login or account ULID", "type": "string" }, "login": { "type": "string" }, "value": { "description": "Account ULID accepted by the corresponding Trail filter", "type": "string" } }, "required": [ "value", "label", "count" ], "type": "object" }, "GlobalProjectTrailFacetResponse": { "additionalProperties": false, "properties": { "buckets": { "items": { "$ref": "#/components/schemas/GlobalProjectTrailFacetBucketResponse" }, "type": [ "array", "null" ] } }, "required": [ "buckets" ], "type": "object" }, "GlobalProjectTrailFacetSetResponse": { "additionalProperties": false, "properties": { "assignee": { "$ref": "#/components/schemas/GlobalProjectTrailFacetResponse" }, "author": { "$ref": "#/components/schemas/GlobalProjectTrailFacetResponse" } }, "type": "object" }, "GlobalProjectTrailFacetsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/GlobalProjectTrailFacetsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "facets": { "$ref": "#/components/schemas/GlobalProjectTrailFacetSetResponse" }, "jurisdiction": { "type": "string" } }, "required": [ "facets", "jurisdiction" ], "type": "object" }, "GlobalProjectTrailGroupTotalResponse": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "rank": { "format": "int64", "type": "integer" }, "totalCount": { "format": "int64", "type": "integer" } }, "required": [ "rank", "key", "label", "totalCount" ], "type": "object" }, "GlobalProjectTrailPageGroupResponse": { "additionalProperties": false, "properties": { "itemCount": { "format": "int64", "type": "integer" }, "key": { "type": "string" }, "label": { "type": "string" }, "rank": { "format": "int64", "type": "integer" }, "totalCount": { "format": "int64", "type": "integer" } }, "required": [ "itemCount", "rank", "key", "label", "totalCount" ], "type": "object" }, "GlobalTrailProjectCapabilitiesResponse": { "additionalProperties": false, "properties": { "canManageTrails": { "type": "boolean" } }, "required": [ "canManageTrails" ], "type": "object" }, "GlobalTrailProjectReferenceResponse": { "additionalProperties": false, "properties": { "forge": { "enum": [ "gh", "et" ], "type": "string" }, "project": { "type": "string" } }, "required": [ "forge", "project" ], "type": "object" }, "GlobalTrailProjectResponse": { "additionalProperties": false, "properties": { "capabilities": { "$ref": "#/components/schemas/GlobalTrailProjectCapabilitiesResponse" }, "id": { "type": "string" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "primaryProcessingCell": { "description": "Core's assigned project cell; empty means routing is unavailable", "type": "string" }, "provider": { "enum": [ "github", "entire" ], "type": "string" }, "reference": { "$ref": "#/components/schemas/GlobalTrailProjectReferenceResponse" } }, "required": [ "id", "name", "provider", "reference", "jurisdiction", "capabilities" ], "type": "object" }, "IPNet": { "additionalProperties": false, "properties": { "IP": { "format": "ipv4", "type": "string" }, "Mask": { "contentEncoding": "base64", "type": "string" } }, "required": [ "IP", "Mask" ], "type": "object" }, "IdentityHandle": { "additionalProperties": false, "properties": { "handle": { "type": "string" }, "is_primary": { "type": "boolean" }, "provider": { "type": "string" } }, "required": [ "provider", "handle" ], "type": "object" }, "InitialTrailChangeBody": { "additionalProperties": false, "properties": { "assignees": {}, "base": {}, "branchAction": {}, "branchName": {}, "priority": {}, "readyForReview": {}, "repositoryId": { "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" }, "status": {}, "title": {}, "type": {} }, "required": [ "repositoryId" ], "type": "object" }, "InvestigationSection": { "additionalProperties": false, "properties": { "keyFindings": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "narrative": { "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "narrative" ], "type": "object" }, "JSONWebKey": { "additionalProperties": false, "properties": { "Algorithm": { "type": "string" }, "CertificateThumbprintSHA1": { "contentEncoding": "base64", "type": "string" }, "CertificateThumbprintSHA256": { "contentEncoding": "base64", "type": "string" }, "Certificates": { "items": { "$ref": "#/components/schemas/Certificate" }, "type": [ "array", "null" ] }, "CertificatesURL": { "$ref": "#/components/schemas/URL" }, "Key": {}, "KeyID": { "type": "string" }, "Use": { "type": "string" } }, "required": [ "Key", "KeyID", "Algorithm", "Use", "Certificates", "CertificatesURL", "CertificateThumbprintSHA1", "CertificateThumbprintSHA256" ], "type": "object" }, "JSONWebKeySet": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/JSONWebKeySet.json" ], "format": "uri", "readOnly": true, "type": "string" }, "keys": { "items": { "$ref": "#/components/schemas/JSONWebKey" }, "type": [ "array", "null" ] } }, "required": [ "keys" ], "type": "object" }, "ManualTrailRunnerLaunchBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ManualTrailRunnerLaunchBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "outcome": { "type": "string" }, "runId": { "type": "string" } }, "required": [ "runId", "outcome" ], "type": "object" }, "MeActivityOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeActivityOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "daily_contributions": { "items": { "$ref": "#/components/schemas/MeDailyContribution" }, "type": [ "array", "null" ] }, "hourly_commit_contributions": { "items": { "$ref": "#/components/schemas/MeHourlyContribution" }, "type": [ "array", "null" ] }, "hourly_contributions": { "items": { "$ref": "#/components/schemas/MeHourlyContribution" }, "type": [ "array", "null" ] }, "repos": { "items": { "$ref": "#/components/schemas/MeRepoContribution" }, "type": [ "array", "null" ] }, "stats": { "$ref": "#/components/schemas/MeActivityStats" } }, "required": [ "stats", "daily_contributions", "hourly_contributions", "hourly_commit_contributions", "repos" ], "type": "object" }, "MeActivityStats": { "additionalProperties": false, "properties": { "continuity_hours": { "format": "double", "type": "number" }, "current_streak": { "format": "int64", "type": "integer" }, "iteration": { "format": "double", "type": "number" }, "lifetime_current_streak": { "format": "int64", "type": "integer" }, "lifetime_streak": { "format": "int64", "type": "integer" }, "orchestration": { "format": "int64", "type": "integer" }, "streak": { "format": "int64", "type": "integer" }, "tasks": { "format": "int64", "type": "integer" }, "throughput": { "format": "double", "type": "number" } }, "required": [ "tasks", "orchestration", "iteration", "throughput", "continuity_hours", "streak", "current_streak", "lifetime_streak", "lifetime_current_streak" ], "type": "object" }, "MeAgentAggregate": { "additionalProperties": false, "properties": { "checkpoints": { "format": "int64", "type": "integer" }, "filesChanged": { "format": "int64", "type": "integer" }, "labels": { "items": { "$ref": "#/components/schemas/MeLabelCount" }, "type": [ "array", "null" ] }, "mcpServers": { "items": { "$ref": "#/components/schemas/MeMcpCount" }, "type": [ "array", "null" ] }, "sessions": { "format": "int64", "type": "integer" }, "skills": { "items": { "$ref": "#/components/schemas/MeSkillCount" }, "type": [ "array", "null" ] }, "tokens": { "format": "int64", "type": "integer" }, "toolMix": { "$ref": "#/components/schemas/MeToolMix" }, "transcriptTokens": { "format": "int64", "type": "integer" } }, "required": [ "sessions", "checkpoints", "tokens", "transcriptTokens", "filesChanged", "labels", "skills", "mcpServers", "toolMix" ], "type": "object" }, "MeAnalysisSummary": { "additionalProperties": false, "properties": { "complete": { "format": "int64", "type": "integer" }, "failed": { "format": "int64", "type": "integer" }, "pending": { "format": "int64", "type": "integer" } }, "required": [ "complete", "pending", "failed" ], "type": "object" }, "MeCheckpointsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeCheckpointsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "checkpoints": { "items": { "$ref": "#/components/schemas/MeUserCheckpoint" }, "type": [ "array", "null" ] }, "cliRepoEnablePendingAccess": { "type": "boolean" }, "cliRepoEnabled": { "type": "boolean" }, "hasCheckpoints": { "type": "boolean" }, "syncing": { "type": "boolean" }, "timeframe": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "checkpoints", "hasCheckpoints", "cliRepoEnabled", "cliRepoEnablePendingAccess", "timeframe", "updated_at", "syncing" ], "type": "object" }, "MeCommit": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "checkpoint_repo_full_name": { "type": [ "string", "null" ] }, "checkpoints": { "items": { "$ref": "#/components/schemas/MeCommitCheckpoint" }, "type": [ "array", "null" ] }, "commit_author_avatar_url": { "type": "string" }, "commit_author_username": { "type": [ "string", "null" ] }, "commit_body": { "type": [ "string", "null" ] }, "commit_date": { "type": [ "string", "null" ] }, "commit_message": { "type": [ "string", "null" ] }, "commit_sha": { "type": "string" }, "commit_subject": { "type": [ "string", "null" ] }, "deletions": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "is_private": { "type": "boolean" }, "repo_full_name": { "type": "string" } }, "required": [ "commit_sha", "commit_message", "commit_subject", "commit_body", "commit_author_username", "commit_date", "additions", "deletions", "files_changed", "checkpoints", "repo_full_name", "is_private", "checkpoint_repo_full_name" ], "type": "object" }, "MeCommitCheckpoint": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "agents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "checkpoint_id": { "type": "string" }, "prompt": { "type": [ "string", "null" ] }, "session_count": { "format": "int64", "type": "integer" }, "total_steps": { "format": "int64", "type": "integer" } }, "required": [ "checkpoint_id", "prompt", "agent", "agents", "session_count", "total_steps" ], "type": "object" }, "MeCommitsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeCommitsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commits": { "items": { "$ref": "#/components/schemas/MeCommit" }, "type": [ "array", "null" ] }, "timeframe": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "commits", "timeframe", "updated_at" ], "type": "object" }, "MeContributorsSummary": { "additionalProperties": false, "properties": { "distinctUsers": { "format": "int64", "type": "integer" }, "totalCheckpoints": { "format": "int64", "type": "integer" }, "totalTokens": { "format": "int64", "type": "integer" } }, "required": [ "distinctUsers", "totalTokens", "totalCheckpoints" ], "type": "object" }, "MeDailyContribution": { "additionalProperties": false, "properties": { "agents": { "$ref": "#/components/schemas/AgentContributions" }, "date": { "type": "string" } }, "required": [ "date", "agents" ], "type": "object" }, "MeDailyCount": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "date": { "type": "string" } }, "required": [ "date", "count" ], "type": "object" }, "MeHourlyContribution": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "date": { "type": "string" }, "hour": { "format": "int64", "type": "integer" }, "value": { "format": "int64", "type": "integer" } }, "required": [ "date", "hour", "agent", "value" ], "type": "object" }, "MeLabelCount": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "label": { "type": "string" } }, "required": [ "label", "count" ], "type": "object" }, "MeMcpCount": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "name": { "type": "string" } }, "required": [ "name", "count" ], "type": "object" }, "MeOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "account_id": { "type": "string" }, "handle": { "type": "string" }, "home_jurisdiction": { "type": "string" }, "jurisdictions": { "description": "Regions where the caller has data; clients federate /me/* across these", "items": { "type": "string" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "account_id", "home_jurisdiction", "jurisdictions", "meta" ], "type": "object" }, "MeProjectTrail": { "additionalProperties": false, "properties": { "assignee_account_ids": { "description": "Account IDs aligned with assignees", "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "assignee_profiles": { "items": { "$ref": "#/components/schemas/MeTrailPerson" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/MeTrailPerson" }, "author_account_id": { "type": "string" }, "body": { "type": "string" }, "capabilities": { "$ref": "#/components/schemas/MeProjectTrailCapabilities" }, "changes": { "description": "Authorized, enabled, processing-local Change readiness for building Trails; empty for other phases, or when meta.partial carries change_readiness_unavailable", "items": { "$ref": "#/components/schemas/MeProjectTrailChange" }, "type": [ "array", "null" ] }, "closed_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "is_possibly_partial": { "type": "boolean" }, "last_activity_at": { "description": "Latest meaningful activity on this Trail or an independently readable Change", "format": "date-time", "type": "string" }, "last_visited_at": { "description": "Caller's last platform read; null if never visited or unavailable", "format": "date-time", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": {}, "type": "object" }, "metadata_updated_at": { "format": "date-time", "type": "string" }, "number": { "format": "int64", "type": "integer" }, "phase": { "enum": [ "planning", "building", "complete", "closed" ], "type": "string" }, "priority": { "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "project": { "$ref": "#/components/schemas/MeTrailProject" }, "repository_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "title": { "type": "string" }, "type": { "enum": [ "bug", "feature", "task" ], "type": "string" }, "url": { "description": "Web app page for this Trail; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "changes", "capabilities", "is_possibly_partial", "id", "project", "number", "title", "body", "status", "phase", "type", "priority", "metadata", "assignees", "assignee_account_ids", "assignee_profiles", "repository_ids", "author_account_id", "created_at", "metadata_updated_at", "last_activity_at", "closed_at", "last_visited_at" ], "type": "object" }, "MeProjectTrailCapabilities": { "additionalProperties": false, "properties": { "can_edit": { "type": "boolean" }, "can_manage_scope": { "type": "boolean" } }, "required": [ "can_edit", "can_manage_scope" ], "type": "object" }, "MeProjectTrailChange": { "additionalProperties": false, "properties": { "branch": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "has_code_changes": { "type": "boolean" }, "id": { "type": "string" }, "last_activity_at": { "format": "date-time", "type": "string" }, "mergeability": { "allOf": [ { "description": "Compact list readiness and stored conflict evidence, not the live repository mergeability response; null for terminal Changes" }, { "$ref": "#/components/schemas/MeProjectTrailMergeability" } ] }, "number": { "format": "int64", "type": "integer" }, "readiness": { "description": "Stored gate/conflict readiness plus current base-branch checks for Changes on building Trails", "enum": [ "ready", "in_review", "none", "unknown" ], "type": "string" }, "ready_for_review": { "description": "Stored review intent; false when mergeability.mergeable is true", "type": "boolean" }, "repository": { "description": "Repository basename, or empty when display metadata has not resolved", "type": "string" }, "repository_id": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "repository_id", "repository", "branch", "number", "title", "status", "has_code_changes", "ready_for_review", "readiness", "mergeability", "created_at", "updated_at", "last_activity_at" ], "type": "object" }, "MeProjectTrailMergeability": { "additionalProperties": false, "properties": { "conflict_status": { "enum": [ "clean", "conflicting", "unknown" ], "type": "string" }, "forge_merge_block": { "type": [ "string", "null" ] }, "head_sha": { "description": "Head of the stored evidence, not necessarily the Change's current head", "type": "string" }, "mergeable": { "description": "True only when current list evidence establishes readiness; merge-time validation remains authoritative", "type": "boolean" }, "refreshed_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "mergeable", "conflict_status", "head_sha", "refreshed_at", "forge_merge_block" ], "type": "object" }, "MeProjectTrailsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeProjectTrailsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/MeProjectTrail" }, "type": [ "array", "null" ] }, "jurisdiction": { "description": "Region whose project Trails this page covers", "type": "string" }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor", "jurisdiction", "meta" ], "type": "object" }, "MeRecapAgentEntry": { "additionalProperties": false, "properties": { "agentId": { "type": "string" }, "agentLabel": { "type": "string" }, "contributors": { "$ref": "#/components/schemas/MeAgentAggregate" }, "me": { "$ref": "#/components/schemas/MeAgentAggregate" } }, "required": [ "agentId", "agentLabel", "me", "contributors" ], "type": "object" }, "MeRecapOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeRecapOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agents": { "additionalProperties": { "$ref": "#/components/schemas/MeRecapAgentEntry" }, "type": "object" }, "contributors": { "$ref": "#/components/schemas/MeContributorsSummary" }, "daily": { "items": { "$ref": "#/components/schemas/MeDailyCount" }, "type": [ "array", "null" ] }, "repo": { "type": [ "string", "null" ] }, "repos": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "since": { "type": "string" }, "summary": { "$ref": "#/components/schemas/MeRecapSummary" }, "timeframe": { "type": "string" }, "until": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "timeframe", "repo", "repos", "since", "until", "agents", "summary", "contributors", "daily", "updated_at" ], "type": "object" }, "MeRecapSummary": { "additionalProperties": false, "properties": { "activeDays": { "format": "int64", "type": "integer" }, "analysis": { "$ref": "#/components/schemas/MeAnalysisSummary" }, "me": { "$ref": "#/components/schemas/MeSummaryTotals" }, "repoCount": { "format": "int64", "type": "integer" }, "team": { "$ref": "#/components/schemas/MeSummaryTotals" }, "transcripts": { "$ref": "#/components/schemas/MeRecapSummaryTranscriptsStruct" } }, "required": [ "me", "team", "repoCount", "activeDays", "analysis", "transcripts" ], "type": "object" }, "MeRecapSummaryTranscriptsStruct": { "additionalProperties": false, "properties": { "me": { "$ref": "#/components/schemas/MeTranscriptStatus" }, "team": { "$ref": "#/components/schemas/MeTranscriptStatus" } }, "required": [ "me", "team" ], "type": "object" }, "MeRepoContribution": { "additionalProperties": false, "properties": { "agents": { "$ref": "#/components/schemas/AgentContributions" }, "repo": { "type": "string" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "repo", "total", "agents" ], "type": "object" }, "MeSessionsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeSessionsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "meta": { "$ref": "#/components/schemas/Meta" }, "sessions": { "items": { "$ref": "#/components/schemas/MeUserSession" }, "type": [ "array", "null" ] }, "timeframe": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "sessions", "timeframe", "updated_at", "meta" ], "type": "object" }, "MeSkillCount": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "skill": { "type": "string" } }, "required": [ "skill", "count" ], "type": "object" }, "MeSummaryTotals": { "additionalProperties": false, "properties": { "checkpoints": { "format": "int64", "type": "integer" }, "sessions": { "format": "int64", "type": "integer" }, "tokens": { "format": "int64", "type": "integer" } }, "required": [ "sessions", "checkpoints", "tokens" ], "type": "object" }, "MeToolMix": { "additionalProperties": false, "properties": { "agent": { "format": "int64", "type": "integer" }, "fileOps": { "format": "int64", "type": "integer" }, "mcp": { "format": "int64", "type": "integer" }, "other": { "format": "int64", "type": "integer" }, "search": { "format": "int64", "type": "integer" }, "shell": { "format": "int64", "type": "integer" } }, "required": [ "shell", "fileOps", "search", "mcp", "agent", "other" ], "type": "object" }, "MeTrail": { "additionalProperties": false, "properties": { "assignee_identities": { "items": { "$ref": "#/components/schemas/TrailAssigneeIdentity" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailAuthor" }, "base": { "type": "string" }, "branch": { "type": [ "string", "null" ] }, "comment_count": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "has_code_changes": { "type": "boolean" }, "id": { "type": "string" }, "is_private": { "type": "boolean" }, "last_activity_at": { "description": "Latest meaningful activity on the Change; excludes background bookkeeping and falls back to created_at until activity is recorded.", "format": "date-time", "type": "string" }, "merged_at": { "format": "date-time", "type": [ "string", "null" ] }, "number": { "format": "int64", "type": "integer" }, "original_branch": { "type": [ "string", "null" ] }, "parent": { "allOf": [ { "description": "Discoverable project parent on list/detail reads; absence does not prove the work is parentless" }, { "$ref": "#/components/schemas/TrailParentReference" } ] }, "phase": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "provider": { "description": "Route identity of the repo the trail lives in: which product surface links to it", "enum": [ "github", "entire" ], "type": "string" }, "ready_for_review": { "type": "boolean" }, "repo_full_name": { "type": "string" }, "repo_id": { "type": "string" }, "reviewers": { "items": { "$ref": "#/components/schemas/TrailReviewer" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "unresolved_count": { "format": "int64", "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "description": "Web app page for this code work; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "provider", "repo_id", "repo_full_name", "is_private", "id", "number", "title", "status", "branch", "original_branch", "base", "type", "priority", "author", "assignees", "assignee_identities", "reviewers", "ready_for_review", "has_code_changes", "comment_count", "unresolved_count", "created_at", "updated_at", "merged_at", "last_activity_at", "phase" ], "type": "object" }, "MeTrailPerson": { "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "avatar_url": { "type": "string" }, "display_name": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "login": { "type": "string" }, "username": { "type": "string" } }, "required": [ "login", "display_name", "identity" ], "type": "object" }, "MeTrailProject": { "additionalProperties": false, "properties": { "can_manage_trails": { "type": "boolean" }, "id": { "type": "string" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "provider": { "enum": [ "github", "entire" ], "type": "string" }, "reference": { "$ref": "#/components/schemas/MeTrailProjectReference" } }, "required": [ "id", "name", "provider", "reference", "jurisdiction", "can_manage_trails" ], "type": "object" }, "MeTrailProjectReference": { "additionalProperties": false, "properties": { "forge": { "enum": [ "gh", "et" ], "type": "string" }, "project": { "type": "string" } }, "required": [ "forge", "project" ], "type": "object" }, "MeTrailsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MeTrailsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "meta": { "$ref": "#/components/schemas/Meta" }, "timeframe": { "type": "string" }, "trails": { "items": { "$ref": "#/components/schemas/MeTrail" }, "type": [ "array", "null" ] }, "updated_at": { "type": "string" } }, "required": [ "trails", "timeframe", "updated_at", "meta" ], "type": "object" }, "MeTranscriptStatus": { "additionalProperties": false, "properties": { "empty": { "format": "int64", "type": "integer" }, "failed": { "format": "int64", "type": "integer" }, "pending": { "format": "int64", "type": "integer" } }, "required": [ "failed", "pending", "empty" ], "type": "object" }, "MeUserCheckpoint": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "branch": { "type": "string" }, "checkpoint_id": { "type": "string" }, "commit_author_github_id": { "format": "int64", "type": [ "integer", "null" ] }, "commit_body": { "type": [ "string", "null" ] }, "commit_date": { "type": [ "string", "null" ] }, "commit_message": { "type": [ "string", "null" ] }, "commit_sha": { "type": "string" }, "commit_subject": { "type": [ "string", "null" ] }, "dead_session_indices": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "deletions": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "input_tokens": { "format": "int64", "type": "integer" }, "is_private": { "type": "boolean" }, "output_tokens": { "format": "int64", "type": "integer" }, "payload_hydration_state": { "type": "string" }, "prompt": { "type": [ "string", "null" ] }, "repo_full_name": { "type": "string" }, "repo_id": { "type": "string" }, "session_count": { "format": "int64", "type": "integer" }, "session_ids": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "sessions": {}, "steps": { "format": "int64", "type": "integer" } }, "required": [ "checkpoint_id", "commit_sha", "commit_message", "commit_subject", "commit_body", "commit_date", "commit_author_github_id", "additions", "deletions", "files_changed", "repo_id", "repo_full_name", "branch", "is_private", "prompt", "steps", "session_count", "session_ids", "sessions", "dead_session_indices", "input_tokens", "output_tokens" ], "type": "object" }, "MeUserSession": { "additionalProperties": false, "properties": { "agent": { "type": [ "string", "null" ] }, "attributionAgentLines": { "format": "int64", "type": [ "integer", "null" ] }, "attributionCalculatedAt": { "type": [ "string", "null" ] }, "attributionHumanAdded": { "format": "int64", "type": [ "integer", "null" ] }, "attributionHumanModified": { "format": "int64", "type": [ "integer", "null" ] }, "attributionHumanRemoved": { "format": "int64", "type": [ "integer", "null" ] }, "attributionTotalCommitted": { "format": "int64", "type": [ "integer", "null" ] }, "cacheCreationTokens": { "format": "int64", "type": [ "integer", "null" ] }, "cacheReadTokens": { "format": "int64", "type": [ "integer", "null" ] }, "checkpointCount": { "format": "int64", "type": "integer" }, "customName": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "firstCommitAuthorAvatarUrl": { "type": "string" }, "firstCommitAuthorUsername": { "type": [ "string", "null" ] }, "inputTokens": { "format": "int64", "type": [ "integer", "null" ] }, "isPublic": { "type": "boolean" }, "is_private": { "type": "boolean" }, "kind": { "type": [ "string", "null" ] }, "lastActivityAt": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "outputTokens": { "format": "int64", "type": [ "integer", "null" ] }, "prompt": { "type": [ "string", "null" ] }, "provider": { "description": "Route identity of the repo the session lives in: which product surface links to it", "enum": [ "github", "entire" ], "type": "string" }, "repo_full_name": { "type": "string" }, "sessionId": { "type": "string" }, "startedAt": { "type": "string" }, "stepCount": { "format": "int64", "type": "integer" }, "subagentCount": { "format": "int64", "type": "integer" } }, "required": [ "provider", "repo_full_name", "is_private", "sessionId", "displayName", "customName", "isPublic", "agent", "model", "kind", "prompt", "firstCommitAuthorUsername", "startedAt", "lastActivityAt", "checkpointCount", "subagentCount", "stepCount", "inputTokens", "outputTokens", "cacheCreationTokens", "cacheReadTokens", "attributionAgentLines", "attributionHumanAdded", "attributionHumanModified", "attributionHumanRemoved", "attributionTotalCommitted", "attributionCalculatedAt" ], "type": "object" }, "MergePreviewOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MergePreviewOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitsAhead": { "format": "int64", "type": "integer" }, "conflictReason": { "description": "treeType | treeMode | blobOverlap | blobBinary; omitted when clean", "type": "string" }, "conflictedPaths": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "mergeBaseSha": { "type": "string" }, "outcome": { "description": "mergeCommit | fastForward | squash | alreadyUpToDate | conflict", "type": "string" }, "resolvedBaseSha": { "type": "string" }, "resolvedHeadSha": { "type": "string" } }, "required": [ "outcome", "conflictedPaths", "commitsAhead" ], "type": "object" }, "Meta": { "additionalProperties": false, "properties": { "degraded": { "description": "Code for degraded behaviour", "type": "string" }, "partial": { "description": "Codes for partial-result conditions: team_stats_foreign_region, unroutable_repos, unroutable_projects, unresolved_caller_login, change_readiness_unavailable", "items": { "type": "string" }, "type": [ "array", "null" ] }, "server_time": { "format": "date-time", "type": "string" } }, "required": [ "server_time" ], "type": "object" }, "MetaAuthorship": { "additionalProperties": false, "properties": { "changedAt": { "description": "RFC3339 author date of the commit that last changed the target", "type": "string" }, "commitSha": { "description": "SHA of the commit that last changed the target", "type": "string" }, "email": { "type": "string" }, "isResolved": { "type": "boolean" }, "name": { "type": "string" }, "reason": { "enum": [ "notFound", "unresolved", "unsupportedTargetType", "noVerdict" ], "type": "string" } }, "required": [ "isResolved" ], "type": "object" }, "MetaExpected": { "additionalProperties": false, "properties": { "isPresent": { "description": "Require the key to currently hold this value (true, with value set) or be absent (false, value ignored).", "type": "boolean" }, "value": { "description": "Required current value when isPresent=true; ignored when isPresent=false.", "type": "string" } }, "required": [ "isPresent" ], "type": "object" }, "MetaItem": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "list": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "set": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "string": { "type": "string" }, "type": { "type": "string" } }, "required": [ "key", "type" ], "type": "object" }, "MetaTarget": { "additionalProperties": false, "properties": { "authorship": { "$ref": "#/components/schemas/MetaAuthorship" }, "items": { "items": { "$ref": "#/components/schemas/MetaItem" }, "type": [ "array", "null" ] }, "target": { "type": "string" } }, "required": [ "target", "items" ], "type": "object" }, "MigrateProjectPreferencesInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/MigrateProjectPreferencesInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "favorite_project_ids": { "items": { "type": "string" }, "maxItems": 1000, "type": [ "array", "null" ] } }, "required": [ "favorite_project_ids" ], "type": "object" }, "Name": { "additionalProperties": false, "properties": { "CommonName": { "type": "string" }, "Country": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "ExtraNames": { "items": { "$ref": "#/components/schemas/AttributeTypeAndValue" }, "type": [ "array", "null" ] }, "Locality": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "Names": { "items": { "$ref": "#/components/schemas/AttributeTypeAndValue" }, "type": [ "array", "null" ] }, "Organization": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "OrganizationalUnit": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "PostalCode": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "Province": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "SerialNumber": { "type": "string" }, "StreetAddress": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "Country", "Organization", "OrganizationalUnit", "Locality", "Province", "StreetAddress", "PostalCode", "SerialNumber", "CommonName", "Names", "ExtraNames" ], "type": "object" }, "OverviewContributorDayItem": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "date": { "type": "string" } }, "required": [ "date", "count" ], "type": "object" }, "OverviewContributorItem": { "additionalProperties": false, "properties": { "account_id": { "type": [ "string", "null" ] }, "commit_count": { "format": "int64", "type": "integer" }, "github_id": { "format": "int64", "type": [ "integer", "null" ] }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "username": { "type": [ "string", "null" ] } }, "required": [ "username", "github_id", "account_id", "commit_count", "identity" ], "type": "object" }, "PRListItem": { "additionalProperties": false, "properties": { "created_at": { "type": "string" }, "draft": { "type": "boolean" }, "html_url": { "type": "string" }, "id": { "format": "int64", "type": "integer" }, "number": { "format": "int64", "type": "integer" }, "repo_full_name": { "type": "string" }, "state": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "number", "title", "html_url", "state", "repo_full_name", "created_at", "updated_at", "draft" ], "type": "object" }, "PRStatDayItem": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "date": { "type": "string" } }, "required": [ "date", "count" ], "type": "object" }, "PRsListOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/PRsListOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "from_db": { "type": "boolean" }, "prs": { "items": { "$ref": "#/components/schemas/PRListItem" }, "type": [ "array", "null" ] }, "updated_at": { "type": "string" } }, "required": [ "prs", "updated_at", "from_db" ], "type": "object" }, "PolicyMapping": { "additionalProperties": false, "properties": { "IssuerDomainPolicy": { "type": "string" }, "SubjectDomainPolicy": { "type": "string" } }, "required": [ "IssuerDomainPolicy", "SubjectDomainPolicy" ], "type": "object" }, "ProblemDocument": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProblemDocument.json" ], "format": "uri", "readOnly": true, "type": "string" }, "code": { "description": "Stable error code; see https://entire.com/errors/.", "type": "string" }, "detail": { "description": "Human-readable explanation; server errors omit internal details.", "type": "string" }, "request_id": { "description": "Request identifier correlated with server logs.", "minLength": 1, "type": "string" }, "status": { "description": "HTTP response status.", "format": "int64", "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "description": "Short description of the HTTP error.", "type": "string" }, "type": { "description": "Documentation URL for this error code.", "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ], "type": "object" }, "ProjectAttachmentCompleteOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectAttachmentCompleteOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "attachment": { "$ref": "#/components/schemas/ProjectAttachmentJSON" } }, "required": [ "attachment" ], "type": "object" }, "ProjectAttachmentIntentBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectAttachmentIntentBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "content_type": {}, "filename": {}, "height": {}, "width": {} }, "type": "object" }, "ProjectAttachmentIntentOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectAttachmentIntentOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "id": { "type": "string" }, "upload": { "$ref": "#/components/schemas/ProjectAttachmentUploadJSON" } }, "required": [ "id", "upload" ], "type": "object" }, "ProjectAttachmentJSON": { "additionalProperties": false, "properties": { "content_type": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by_account_id": { "type": "string" }, "filename": { "type": "string" }, "height": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "type": "string" }, "is_ready": { "type": "boolean" }, "kind": { "type": "string" }, "project_id": { "type": "string" }, "size_bytes": { "format": "int64", "type": "integer" }, "trail_id": { "type": "string" }, "width": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "project_id", "trail_id", "filename", "content_type", "size_bytes", "is_ready", "kind", "created_by_account_id", "created_at", "width", "height" ], "type": "object" }, "ProjectAttachmentListOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectAttachmentListOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "attachments": { "items": { "$ref": "#/components/schemas/ProjectAttachmentJSON" }, "type": [ "array", "null" ] } }, "required": [ "attachments" ], "type": "object" }, "ProjectAttachmentUploadJSON": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "type": "string" }, "max_bytes": { "format": "int64", "type": "integer" }, "url": { "type": "string" } }, "required": [ "url", "expires_at", "max_bytes" ], "type": "object" }, "ProjectPreferences": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectPreferences.json" ], "format": "uri", "readOnly": true, "type": "string" }, "favorite_project_ids": { "description": "Favorite project IDs. This preference does not grant project access.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "favorite_project_ids" ], "type": "object" }, "ProjectTimelineEvent": { "additionalProperties": false, "type": "object" }, "ProjectTrailCapabilitiesResponse": { "additionalProperties": false, "properties": { "canEdit": { "type": "boolean" }, "canManageScope": { "type": "boolean" } }, "required": [ "canEdit", "canManageScope" ], "type": "object" }, "ProjectTrailChangeReadiness": { "additionalProperties": false, "properties": { "base": { "type": "string" }, "branch": { "description": "Active head branch; empty when detached", "type": "string" }, "createdAt": { "type": "string" }, "deployments": { "allOf": [ { "description": "Deployment rollup at the Change head; display-only, never affects readiness. Present on project Trail detail and update responses, never on lists." }, { "$ref": "#/components/schemas/DeploymentSummary" } ] }, "ghPrId": { "format": "int64", "type": "integer" }, "hasCodeChanges": { "type": "boolean" }, "id": { "type": "string" }, "lastActivityAt": { "type": "string" }, "mergeability": { "allOf": [ { "description": "Stored conflict evidence only; null for terminal Changes or when the snapshot is unavailable. Unknown evidence cannot establish readiness." }, { "$ref": "#/components/schemas/ProjectTrailStoredMergeability" } ] }, "number": { "format": "int64", "type": "integer" }, "originalBranch": { "type": "string" }, "readiness": { "description": "Readiness projected from stored gates, conflicts, and database-backed base-branch CI snapshots; unknown when evidence cannot establish readiness. Lists and addressed Trail responses use the same evidence sources.", "enum": [ "ready", "in_review", "none", "unknown" ], "type": "string" }, "repository": { "description": "Repository basename, or empty when display metadata has not resolved", "type": "string" }, "repositoryId": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "readiness", "mergeability", "id", "repositoryId", "repository", "branch", "originalBranch", "base", "number", "title", "status", "hasCodeChanges", "createdAt", "updatedAt", "lastActivityAt" ], "type": "object" }, "ProjectTrailCreateBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectTrailCreateBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "assignees": { "description": "Actor references: ulid:ACCOUNT_ID or @username. A bare string is a GitHub login (legacy).", "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "body": { "maxLength": 1048576, "type": "string" }, "changes": { "description": "Initial branch-backed Changes; all database writes commit together", "items": { "$ref": "#/components/schemas/InitialTrailChangeBody" }, "maxItems": 100, "type": [ "array", "null" ] }, "metadata": { "additionalProperties": {}, "type": "object" }, "priority": { "default": "none", "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "repoIds": { "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] }, "status": { "default": "open", "enum": [ "open", "closed" ], "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "type": "string" }, "type": { "default": "task", "enum": [ "bug", "feature", "task" ], "type": "string" } }, "required": [ "title" ], "type": "object" }, "ProjectTrailListItemResponse": { "additionalProperties": false, "properties": { "assigneeAccountIds": { "description": "Account IDs aligned with assignees", "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "assigneeProfiles": { "items": { "$ref": "#/components/schemas/TrailPersonResponse" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailPersonResponse" }, "authorAccountId": { "type": "string" }, "body": { "description": "Markdown until the first editor-backed body write; a plain-text projection thereafter. Rich content is in bodyDocument.", "type": "string" }, "bodyDocument": { "allOf": [ { "description": "Rich body snapshot on detail responses; omitted from lists. No CRDT state." }, { "$ref": "#/components/schemas/TrailBodyDocumentJSON" } ] }, "capabilities": { "$ref": "#/components/schemas/ProjectTrailCapabilitiesResponse" }, "changes": { "description": "Compact authorized Change readiness for building Trails; empty otherwise", "items": { "$ref": "#/components/schemas/ProjectTrailChangeReadiness" }, "type": [ "array", "null" ] }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "groupKey": { "description": "Membership key in groupTotals; empty for the ungrouped collection", "type": "string" }, "id": { "type": "string" }, "isPossiblyPartial": { "description": "True when access filtering means repoIds or changes must not be interpreted as a complete aggregate; this is conservative and does not indicate that any item was omitted", "type": "boolean" }, "lastActivityAt": { "description": "Latest meaningful activity on this Trail or an independently readable Change; excludes background bookkeeping", "type": "string" }, "lastVisitedAt": { "description": "Caller's last platform read; null if never visited, unavailable, or caller is not an account", "format": "date-time", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": {}, "type": "object" }, "metadataUpdatedAt": { "description": "When this Trail's own fields last changed; use the response ETag for If-Match", "type": "string" }, "number": { "format": "int64", "type": "integer" }, "phase": { "description": "Derived project lifecycle phase; closed follows the project Trail status, while other phases inherit repository Change progress", "enum": [ "planning", "building", "complete", "closed" ], "type": "string" }, "priority": { "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "project": { "$ref": "#/components/schemas/GlobalTrailProjectResponse" }, "projectId": { "type": "string" }, "readiness": { "description": "Stored gate/conflict readiness plus current base-branch checks; unknown when required evidence is unavailable or stale", "enum": [ "ready", "in_review", "none", "unknown" ], "type": "string" }, "repoIds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "enum": [ "open", "closed" ], "type": "string" }, "title": { "type": "string" }, "type": { "enum": [ "bug", "feature", "task" ], "type": "string" }, "url": { "description": "Web app page for this Trail; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "groupKey", "readiness", "changes", "id", "projectId", "number", "title", "body", "status", "phase", "metadata", "type", "priority", "assignees", "assigneeAccountIds", "repoIds", "authorAccountId", "createdAt", "metadataUpdatedAt", "closedAt", "lastVisitedAt", "lastActivityAt" ], "type": "object" }, "ProjectTrailRepositoriesResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectTrailRepositoriesResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "repositories": { "items": { "$ref": "#/components/schemas/ProjectTrailRepositoryResponse" }, "type": [ "array", "null" ] } }, "required": [ "repositories" ], "type": "object" }, "ProjectTrailRepositoryResponse": { "additionalProperties": false, "properties": { "forge": { "type": "string" }, "full_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "full_name", "forge" ], "type": "object" }, "ProjectTrailStoredMergeability": { "additionalProperties": false, "properties": { "conflict_status": { "enum": [ "clean", "conflicting", "unknown" ], "type": "string" }, "forge_merge_block": { "type": [ "string", "null" ] }, "head_sha": { "description": "Head of the stored evidence, not necessarily the Change's current head", "type": "string" }, "refreshed_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "conflict_status", "head_sha", "refreshed_at", "forge_merge_block" ], "type": "object" }, "ProjectTrailTimelineResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectTrailTimelineResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/ProjectTimelineEvent" }, "type": [ "array", "null" ] }, "next_cursor": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "ProjectTrailUpdateBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectTrailUpdateBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "assignees": { "description": "Actor references: ulid:ACCOUNT_ID or @username. A bare string is a GitHub login (legacy).", "items": { "type": "string" }, "maxItems": 100, "type": "array" }, "body": { "description": "Markdown input. When an editor document exists, updates its rich content and stores the plain-text projection in body.", "maxLength": 1048576, "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "priority": { "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "repoIds": { "items": { "type": "string" }, "maxItems": 100, "type": "array" }, "status": { "enum": [ "open", "closed" ], "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "type": "string" }, "type": { "enum": [ "bug", "feature", "task" ], "type": "string" } }, "type": "object" }, "ProjectTrailsListResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ProjectTrailsListResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "capabilities": { "allOf": [ { "description": "Caller permissions for the addressed project, including when the collection is empty" }, { "$ref": "#/components/schemas/GlobalTrailProjectCapabilitiesResponse" } ] }, "groupBy": { "type": "string" }, "groupTotals": { "items": { "$ref": "#/components/schemas/GlobalProjectTrailGroupTotalResponse" }, "type": [ "array", "null" ] }, "groups": { "items": { "$ref": "#/components/schemas/GlobalProjectTrailPageGroupResponse" }, "type": [ "array", "null" ] }, "items": { "items": { "$ref": "#/components/schemas/ProjectTrailListItemResponse" }, "type": [ "array", "null" ] }, "jurisdiction": { "type": "string" }, "nextPageToken": { "type": [ "string", "null" ] } }, "required": [ "capabilities", "items", "groups", "groupTotals", "groupBy", "jurisdiction", "nextPageToken" ], "type": "object" }, "PublicSharingInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/PublicSharingInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "enabled": { "type": "boolean" } }, "type": "object" }, "PublicSharingOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/PublicSharingOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "public_sharing_enabled": { "type": "boolean" } }, "required": [ "public_sharing_enabled" ], "type": "object" }, "RecapAgent": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "checkpoints": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "sessions": { "format": "int64", "type": "integer" }, "tokens": { "format": "int64", "type": "integer" } }, "required": [ "agent", "sessions", "checkpoints", "tokens", "files_changed" ], "type": "object" }, "RecapOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RecapOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agents": { "items": { "$ref": "#/components/schemas/RecapAgent" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "repo": { "type": "string" }, "summary": { "$ref": "#/components/schemas/SummaryStruct" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "agents", "summary", "updated_at", "meta" ], "type": "object" }, "RecentBodyInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RecentBodyInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "forge": { "description": "Forge full_name lives on (github or entire); required with full_name.", "type": "string" }, "full_name": { "type": "string" }, "repo_id": { "type": "string" } }, "type": "object" }, "RepoAgentActivityOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoAgentActivityOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "daily": { "items": { "$ref": "#/components/schemas/AgentActivityDayItem" }, "type": [ "array", "null" ] }, "since": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] } }, "required": [ "daily", "branch", "since", "until" ], "type": "object" }, "RepoBranchCommitDatesOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoBranchCommitDatesOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branches": { "items": { "$ref": "#/components/schemas/BranchCommitDays" }, "type": [ "array", "null" ] }, "since": { "type": "string" }, "until": { "type": "string" } }, "required": [ "branches", "since", "until" ], "type": "object" }, "RepoCapabilities": { "additionalProperties": false, "properties": { "can_manage_access": { "type": "boolean" }, "can_manage_settings": { "type": "boolean" }, "data_role": { "type": "string" } }, "required": [ "data_role", "can_manage_settings", "can_manage_access" ], "type": "object" }, "RepoCheckpointMetricsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoCheckpointMetricsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "avg_messages_per_checkpoint": { "format": "double", "type": "number" }, "avg_sessions_per_checkpoint": { "format": "double", "type": "number" }, "avg_tokens_per_checkpoint": { "format": "double", "type": "number" }, "branch": { "type": "string" }, "checkpoint_count": { "format": "int64", "type": "integer" }, "since": { "type": [ "string", "null" ] }, "tokens_per_message": { "format": "int64", "type": "integer" }, "total_messages": { "format": "int64", "type": "integer" }, "until": { "type": [ "string", "null" ] } }, "required": [ "checkpoint_count", "avg_tokens_per_checkpoint", "avg_sessions_per_checkpoint", "total_messages", "avg_messages_per_checkpoint", "tokens_per_message", "branch", "since", "until" ], "type": "object" }, "RepoCheckpointsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoCheckpointsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "app_has_access": { "type": "boolean" }, "checkpoints": { "items": { "$ref": "#/components/schemas/CheckpointInfo" }, "type": [ "array", "null" ] }, "history_complete": { "type": "boolean" }, "history_status": { "type": "string" }, "repo_full_name": { "type": "string" }, "session_branch_exists": { "type": "boolean" }, "source": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "checkpoints", "repo_full_name", "updated_at", "source", "app_has_access", "session_branch_exists", "history_status", "history_complete" ], "type": "object" }, "RepoCollaboratorItem": { "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "handle": { "type": "string" }, "role": { "type": "string" }, "username": { "description": "Entire username; omitted until claimed", "type": "string" } }, "required": [ "accountId", "handle", "role" ], "type": "object" }, "RepoCollaboratorsBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoCollaboratorsBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/RepoCollaboratorItem" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "RepoCommitListItem": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": [ "integer", "null" ] }, "checkpoints": { "items": { "$ref": "#/components/schemas/CommitCheckpointInfo" }, "type": [ "array", "null" ] }, "commitAuthor": { "type": "string" }, "commitAuthorAvatarUrl": { "type": "string" }, "commitAuthorIdentity": { "$ref": "#/components/schemas/ContributorIdentity" }, "commitAuthorUsername": { "type": [ "string", "null" ] }, "commitBody": { "type": [ "string", "null" ] }, "commitDate": { "type": "string" }, "commitMessage": { "type": "string" }, "commitSha": { "type": "string" }, "commitSubject": { "type": "string" }, "deletions": { "format": "int64", "type": [ "integer", "null" ] }, "fileStats": { "items": { "$ref": "#/components/schemas/FileStats" }, "type": [ "array", "null" ] }, "filesChanged": { "format": "int64", "type": [ "integer", "null" ] }, "filesTouched": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "commitSha", "commitMessage", "commitSubject", "commitBody", "commitAuthor", "commitAuthorUsername", "commitDate", "additions", "deletions", "filesChanged", "filesTouched", "fileStats", "url", "checkpoints" ], "type": "object" }, "RepoCommitStatsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoCommitStatsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "daily": { "items": { "$ref": "#/components/schemas/CommitStatDayItem" }, "type": [ "array", "null" ] }, "last_activity_at": { "type": [ "string", "null" ] }, "since": { "type": [ "string", "null" ] }, "total": { "format": "int64", "type": "integer" }, "until": { "type": [ "string", "null" ] }, "with_checkpoint": { "format": "int64", "type": "integer" }, "without_checkpoint": { "format": "int64", "type": "integer" } }, "required": [ "total", "with_checkpoint", "without_checkpoint", "last_activity_at", "daily", "branch", "since", "until" ], "type": "object" }, "RepoCommitsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoCommitsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "app_has_access": { "type": "boolean" }, "commits": { "items": { "$ref": "#/components/schemas/RepoCommitListItem" }, "type": [ "array", "null" ] }, "from_cache": { "type": "boolean" }, "has_more": { "type": "boolean" }, "history_complete": { "type": "boolean" }, "history_pages_fetched": { "format": "int64", "type": "integer" }, "history_status": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "format": "int64", "type": [ "integer", "null" ] }, "repo_full_name": { "type": "string" }, "session_branch_exists": { "type": "boolean" }, "updated_at": { "type": "string" } }, "required": [ "commits", "repo_full_name", "updated_at", "app_has_access", "session_branch_exists", "history_status", "history_complete", "history_pages_fetched", "has_more", "next_offset", "next_cursor", "from_cache" ], "type": "object" }, "RepoContributorAgentsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoContributorAgentsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "contributors": { "items": { "$ref": "#/components/schemas/ContributorAgentsItem" }, "type": [ "array", "null" ] }, "since": { "type": [ "string", "null" ] }, "total_commits": { "format": "int64", "type": "integer" }, "until": { "type": [ "string", "null" ] } }, "required": [ "total_commits", "contributors", "branch", "since", "until" ], "type": "object" }, "RepoContributorTokensOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoContributorTokensOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "contributors": { "items": { "$ref": "#/components/schemas/ContributorTokenItem" }, "type": [ "array", "null" ] }, "since": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] } }, "required": [ "contributors", "branch", "since", "until" ], "type": "object" }, "RepoContributorsOverviewOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoContributorsOverviewOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "daily": { "items": { "$ref": "#/components/schemas/OverviewContributorDayItem" }, "type": [ "array", "null" ] }, "since": { "type": [ "string", "null" ] }, "top_contributors": { "items": { "$ref": "#/components/schemas/OverviewContributorItem" }, "type": [ "array", "null" ] }, "total_contributors": { "format": "int64", "type": "integer" }, "until": { "type": [ "string", "null" ] } }, "required": [ "total_contributors", "top_contributors", "daily", "branch", "since", "until" ], "type": "object" }, "RepoIDBodyInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoIDBodyInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "repo_id": { "type": "string" } }, "type": "object" }, "RepoListItem": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoListItem.json" ], "format": "uri", "readOnly": true, "type": "string" }, "activity": { "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "archived": { "type": "boolean" }, "auto_run_on_push": { "type": "boolean" }, "capabilities": { "$ref": "#/components/schemas/RepoCapabilities" }, "checkpoint_count": { "format": "int64", "type": "integer" }, "default_branch": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "full_name": { "type": "string" }, "github_id": { "format": "int64", "type": "integer" }, "html_url": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "language": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "open_pr_count": { "format": "int64", "type": "integer" }, "owning_project_id": { "description": "Owning project ULID", "type": "string" }, "permission": { "type": "string" }, "private": { "type": "boolean" }, "public_sharing_enabled": { "type": "boolean" }, "repo_group_id": { "type": "string" }, "runners_enabled": { "type": "boolean" }, "stargazers_count": { "format": "int64", "type": "integer" }, "trails_enabled": { "type": "boolean" }, "updated_at": { "type": "string" }, "viewer_can_see_checkpoint_data": { "type": "boolean" } }, "required": [ "owning_project_id", "id", "github_id", "name", "full_name", "description", "html_url", "stargazers_count", "language", "private", "archived", "updated_at", "default_branch", "permission", "capabilities", "checkpoint_count", "viewer_can_see_checkpoint_data", "runners_enabled", "trails_enabled", "auto_run_on_push", "public_sharing_enabled", "open_pr_count" ], "type": "object" }, "RepoMetaReadOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoMetaReadOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/MetaItem" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "RepoMetaTargetsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoMetaTargetsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/MetaTarget" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "RepoMetaWriteInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoMetaWriteInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "expected": { "allOf": [ { "description": "Optional key-scoped compare-and-swap precondition for set/rm: apply only if the key's current value matches (or, isPresent=false, only if currently absent). Omit for unconditional behavior. Unsupported with list:push/list:rm/set:add/set:rm." }, { "$ref": "#/components/schemas/MetaExpected" } ] }, "key": { "description": "Colon-namespaced metadata key, e.g. agent:model", "type": "string" }, "op": { "description": "git-meta verb: set, rm, list:push, list:rm, set:add, set:rm", "type": "string" }, "target": { "description": "git-meta target: commit:\u003csha\u003e, branch:\u003cname\u003e, path:\u003cp\u003e, change-id:\u003cid\u003e, or project", "type": "string" }, "value": { "description": "Value for set/list:push/set:add/list:rm/set:rm; ignored for rm", "type": "string" } }, "required": [ "op", "target", "key" ], "type": "object" }, "RepoPRStatsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoPRStatsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "merged": { "format": "int64", "type": "integer" }, "merged_daily": { "items": { "$ref": "#/components/schemas/PRStatDayItem" }, "type": [ "array", "null" ] }, "opened": { "format": "int64", "type": "integer" }, "opened_daily": { "items": { "$ref": "#/components/schemas/PRStatDayItem" }, "type": [ "array", "null" ] }, "since": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] } }, "required": [ "opened", "merged", "opened_daily", "merged_daily", "since", "until" ], "type": "object" }, "RepoPreferenceItem": { "additionalProperties": false, "properties": { "full_name": { "type": "string" }, "last_used_at": { "description": "Timestamp from this caller's retained recent list, including unpin/import recency. Null when unavailable.", "format": "date-time", "type": [ "string", "null" ] }, "provider": { "description": "Forge the repo lives on. Omitted when neither this region nor Core knows it.", "enum": [ "github", "entire" ], "type": "string" }, "repo_id": { "type": "string" }, "runners_enabled": { "type": "boolean" }, "trails_enabled": { "type": "boolean" } }, "required": [ "repo_id", "full_name", "runners_enabled", "trails_enabled", "last_used_at" ], "type": "object" }, "RepoPreferenceMigrationEntry": { "additionalProperties": false, "properties": { "full_name": { "type": "string" }, "github_id": { "format": "int64", "type": "integer" } }, "required": [ "github_id", "full_name" ], "type": "object" }, "RepoPreferencesMigrateInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoPreferencesMigrateInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "pinned": { "items": { "$ref": "#/components/schemas/RepoPreferenceMigrationEntry" }, "maxItems": 500, "type": [ "array", "null" ] }, "recent": { "items": { "$ref": "#/components/schemas/RepoPreferenceMigrationEntry" }, "maxItems": 500, "type": [ "array", "null" ] } }, "type": "object" }, "RepoPreferencesOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoPreferencesOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "pinned": { "items": { "$ref": "#/components/schemas/RepoPreferenceItem" }, "type": [ "array", "null" ] }, "recent": { "items": { "$ref": "#/components/schemas/RepoPreferenceItem" }, "type": [ "array", "null" ] } }, "required": [ "pinned", "recent" ], "type": "object" }, "RepoRunnerAdmission": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoRunnerAdmission.json" ], "format": "uri", "readOnly": true, "type": "string" }, "billing_subject": { "allOf": [ { "description": "Who pays for the repository's runs; null when core named none." }, { "$ref": "#/components/schemas/BillingSubjectRef" } ] }, "paused_by": { "description": "Who paused runs: billing, or operator for an operator, customer-denied or internal-only refusal. An open enum; null when runs are not paused.", "type": [ "string", "null" ] }, "runs_paused": { "type": "boolean" } }, "required": [ "runs_paused", "paused_by", "billing_subject" ], "type": "object" }, "RepoSecretMetaItem": { "additionalProperties": false, "properties": { "secretKey": { "description": "Which secret is configured (e.g. api_key_anthropic).", "type": "string" }, "updatedAt": { "description": "When the secret was last set or rotated (RFC3339, milliseconds).", "type": "string" } }, "required": [ "secretKey", "updatedAt" ], "type": "object" }, "RepoSecretPutInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoSecretPutInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "value": { "description": "The secret value to store (e.g. an Anthropic or OpenAI API key). Stored encrypted; never returned by any endpoint.", "maxLength": 4096, "minLength": 1, "type": "string" } }, "required": [ "value" ], "type": "object" }, "RepoSecretsListOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoSecretsListOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/RepoSecretMetaItem" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "RepoSessionPatternsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoSessionPatternsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "by_hour": { "items": { "$ref": "#/components/schemas/SessionPatternHourItem" }, "type": [ "array", "null" ] }, "by_weekday": { "items": { "$ref": "#/components/schemas/SessionPatternWeekdayItem" }, "type": [ "array", "null" ] }, "depth_buckets": { "items": { "$ref": "#/components/schemas/SessionPatternDepthItem" }, "type": [ "array", "null" ] }, "since": { "type": [ "string", "null" ] }, "until": { "type": [ "string", "null" ] }, "velocity_by_date": { "items": { "$ref": "#/components/schemas/SessionPatternVelocityItem" }, "type": [ "array", "null" ] } }, "required": [ "by_hour", "by_weekday", "depth_buckets", "velocity_by_date", "branch", "since", "until" ], "type": "object" }, "RepoSessionsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoSessionsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "app_has_access": { "type": "boolean" }, "facets": { "$ref": "#/components/schemas/SessionListFacets" }, "history_complete": { "type": "boolean" }, "history_status": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ] }, "repo_full_name": { "type": "string" }, "session_branch_exists": { "type": "boolean" }, "sessions": { "items": { "$ref": "#/components/schemas/SessionListItem" }, "type": [ "array", "null" ] }, "source": { "type": "string" } }, "required": [ "sessions", "next_cursor", "repo_full_name", "app_has_access", "session_branch_exists", "history_status", "history_complete", "source" ], "type": "object" }, "RepoSummaryOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoSummaryOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "meta": { "$ref": "#/components/schemas/Meta" }, "repo_id": { "type": "string" }, "summary": { "$ref": "#/components/schemas/SummaryBody" }, "timeframe": { "type": "string" } }, "required": [ "repo_id", "timeframe", "summary", "meta" ], "type": "object" }, "RepoTLDROutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoTLDROutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "type": "string" }, "hasSummary": { "type": "boolean" }, "isPending": { "type": "boolean" }, "isRefreshing": { "type": "boolean" }, "markdown": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "sections": { "items": { "$ref": "#/components/schemas/RepoTLDRSection" }, "type": [ "array", "null" ] }, "sources": { "$ref": "#/components/schemas/RepoTLDRSources" } }, "required": [ "markdown", "sections", "hasSummary", "model", "branch", "sources" ], "type": "object" }, "RepoTLDRSection": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "markdown": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title", "markdown" ], "type": "object" }, "RepoTLDRSources": { "additionalProperties": false, "properties": { "checkpoints30dCount": { "format": "int64", "type": "integer" }, "commits30dCount": { "format": "int64", "type": "integer" }, "hasReadme": { "type": "boolean" } }, "required": [ "hasReadme", "commits30dCount", "checkpoints30dCount" ], "type": "object" }, "RepoWatchersBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepoWatchersBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "trails": { "additionalProperties": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": "object" } }, "required": [ "trails" ], "type": "object" }, "ReposBatchInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReposBatchInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "ids": { "description": "Repo ids to authorize and hydrate", "items": { "type": "string" }, "maxItems": 500, "type": [ "array", "null" ] }, "include": { "description": "Extra computed fields to include; supported: activity", "items": { "enum": [ "activity" ], "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "ids" ], "type": "object" }, "ReposListOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReposListOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "from_db": { "type": "boolean" }, "repos": { "items": { "$ref": "#/components/schemas/RepoListItem" }, "type": [ "array", "null" ] }, "updated_at": { "type": "string" } }, "required": [ "repos", "updated_at", "from_db" ], "type": "object" }, "RepositoryAgent": { "additionalProperties": false, "properties": { "description": { "description": "Free-form description; empty when unset.", "type": "string" }, "harness": { "description": "Agent CLI that runs it.", "type": "string" }, "id": { "description": "Agent id (ULID).", "type": "string" }, "is_enabled": { "description": "Whether its trigger runs it.", "type": "boolean" }, "latest_reading": { "allOf": [ { "description": "The latest finished reading in this repository of the signal's current value type; null until one exists." }, { "$ref": "#/components/schemas/TrailAgentReadingJSON" } ] }, "latest_run": { "allOf": [ { "description": "The agent's latest run in this repository, finished or not; null before its first." }, { "$ref": "#/components/schemas/RepositoryAgentRun" } ] }, "model": { "description": "Model passed to the harness; null uses the harness default.", "type": [ "string", "null" ] }, "name": { "description": "The agent's name; a preset agent's is its preset's.", "type": "string" }, "preset": { "allOf": [ { "description": "The Entire preset the agent runs, or null for a custom agent." }, { "$ref": "#/components/schemas/AgentPresetRef" } ] }, "signal": { "allOf": [ { "description": "The agent's signal: each review distilled into one reading." }, { "$ref": "#/components/schemas/AgentSignal" } ] }, "triggers": { "description": "Zero or one trigger; empty means the agent only runs when asked to.", "items": { "$ref": "#/components/schemas/AgentTrigger" }, "type": [ "array", "null" ] } }, "required": [ "id", "name", "description", "preset", "harness", "model", "signal", "is_enabled", "triggers", "latest_run", "latest_reading" ], "type": "object" }, "RepositoryAgentRun": { "additionalProperties": false, "properties": { "change_id": { "description": "The Change it reviewed.", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error": { "allOf": [ { "description": "Why the run failed or timed out, or why Entire canceled it; null otherwise." }, { "$ref": "#/components/schemas/RunError" } ] }, "head_sha": { "description": "The head it reviewed; null before the run resolved it.", "type": [ "string", "null" ] }, "id": { "description": "The run (GET .../runs/{id}).", "type": "string" }, "status": { "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" }, "trail_id": { "description": "The product Trail of the Change it reviewed.", "type": "string" }, "trigger": { "$ref": "#/components/schemas/RunTrigger" } }, "required": [ "id", "status", "trigger", "trail_id", "change_id", "head_sha", "error", "created_at" ], "type": "object" }, "RepositoryAgentsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepositoryAgentsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/RepositoryAgent" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "RepositoryRun": { "additionalProperties": false, "properties": { "agent": { "allOf": [ { "description": "The agent, at the version and under the name the run pinned." }, { "$ref": "#/components/schemas/RunAgent" } ] }, "attempt": { "format": "int64", "type": "integer" }, "change_id": { "description": "The Change it reviewed.", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error": { "allOf": [ { "description": "Why the run failed or timed out, or why Entire canceled it (its agent was paused or archived, or its branch advanced); null otherwise, including for a run canceled through the cancel route." }, { "$ref": "#/components/schemas/RunError" } ] }, "id": { "description": "The run (GET /repos/{repo_id}/runs/{id}).", "type": "string" }, "retry_of": { "type": [ "string", "null" ] }, "status": { "description": "The run's status: queued (waiting for a sandbox), running, succeeded, failed, timed_out or canceled.", "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" }, "trail_id": { "description": "The product Trail of the Change it reviewed.", "type": "string" }, "trigger": { "$ref": "#/components/schemas/RunTrigger" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_by_model": { "description": "Token usage the agent reported, as usageByModel on the runner runs' routes; null until the first report. One entry with the run's unsplit total until runs record a per-model split. Price an entry at its model's rate only when model is set; a null model means an unsplit total across several models or unavailable model attribution.", "items": { "$ref": "#/components/schemas/RunModelUsage" }, "type": [ "array", "null" ] } }, "required": [ "id", "agent", "status", "trigger", "trail_id", "change_id", "error", "attempt", "retry_of", "usage_by_model", "created_at", "updated_at" ], "type": "object" }, "RepositoryRunCreate": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RepositoryRunCreate.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agent_id": { "description": "An unarchived agent of the project that owns the repository (ULID).", "type": "string" }, "head_sha": { "description": "Optional commit pin: the run is refused (409) if the Change's head is no longer this commit.", "type": "string" }, "target": { "$ref": "#/components/schemas/RunTargetInput" } }, "required": [ "agent_id", "target" ], "type": "object" }, "ResolvedRepoCommit": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": [ "integer", "null" ] }, "checkpoints": { "items": { "$ref": "#/components/schemas/CommitCheckpointInfo" }, "type": [ "array", "null" ] }, "commitAuthor": { "type": "string" }, "commitAuthorAvatarUrl": { "type": "string" }, "commitAuthorIdentity": { "$ref": "#/components/schemas/ContributorIdentity" }, "commitAuthorUsername": { "type": [ "string", "null" ] }, "commitBody": { "type": [ "string", "null" ] }, "commitDate": { "type": "string" }, "commitMessage": { "type": "string" }, "commitSha": { "type": "string" }, "commitSubject": { "type": "string" }, "deletions": { "format": "int64", "type": [ "integer", "null" ] }, "fileStats": { "items": { "$ref": "#/components/schemas/FileStats" }, "type": [ "array", "null" ] }, "filesChanged": { "format": "int64", "type": [ "integer", "null" ] }, "filesTouched": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "trailNumber": { "description": "Most recently updated change whose head is this commit; see trailNumbers when several share it", "format": "int64", "type": [ "integer", "null" ] }, "trailNumbers": { "description": "All repository-local change numbers whose head is this commit, ascending", "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "url": { "type": [ "string", "null" ] } }, "required": [ "trailNumber", "trailNumbers", "commitSha", "commitMessage", "commitSubject", "commitBody", "commitAuthor", "commitAuthorUsername", "commitDate", "additions", "deletions", "filesChanged", "filesTouched", "fileStats", "url", "checkpoints" ], "type": "object" }, "ReviewCommentBatchErrorJSON": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "field", "retryable" ], "type": "object" }, "ReviewCommentBatchRequestJSON": { "additionalProperties": false, "properties": { "body": { "maxLength": 65536, "type": [ "string", "null" ] }, "client_id": { "maxLength": 255, "minLength": 1, "type": "string" }, "confidence": { "format": "double", "maximum": 1, "minimum": 0, "type": [ "number", "null" ] }, "location": { "$ref": "#/components/schemas/ReviewCommentLocationInputJSON" }, "severity": { "enum": [ "high", "medium", "low" ], "type": [ "string", "null" ] }, "status": { "enum": [ "open", "resolved", "dismissed" ], "type": "string" }, "status_reason": { "maxLength": 4096, "type": [ "string", "null" ] }, "suggested_change": { "anyOf": [ { "$ref": "#/components/schemas/ReviewSuggestedChangeInputJSON" }, { "type": "null" } ] } }, "required": [ "client_id", "location" ], "type": "object" }, "ReviewCommentBatchResultJSON": { "additionalProperties": false, "properties": { "client_id": { "type": "string" }, "comment": { "$ref": "#/components/schemas/ReviewCommentJSON" }, "error": { "$ref": "#/components/schemas/ReviewCommentBatchErrorJSON" }, "status": { "type": "string" }, "suggested_change": { "$ref": "#/components/schemas/SuggestedChangeJSON" } }, "required": [ "client_id", "status" ], "type": "object" }, "ReviewCommentJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewCommentJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "actor_display_name": { "type": [ "string", "null" ] }, "actor_id": { "type": [ "string", "null" ] }, "actor_identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "agent_verdict": { "allOf": [ { "description": "The latest verdict the agent that raised this finding gave on it in a later run; absent until one has." }, { "$ref": "#/components/schemas/FindingVerdictJSON" } ] }, "body": { "type": [ "string", "null" ] }, "client_id": { "type": [ "string", "null" ] }, "client_id_hash": { "type": [ "string", "null" ] }, "code_version_id": { "type": "string" }, "confidence": { "format": "double", "type": [ "number", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "discussion_id": { "type": [ "string", "null" ] }, "discussion_message_count": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "location": { "$ref": "#/components/schemas/CommentLocationJSON" }, "repo_id": { "type": "string" }, "review_id": { "type": "string" }, "severity": { "type": [ "string", "null" ] }, "source": { "allOf": [ { "description": "The agent run whose review published this finding; absent for every other comment. actor_id stays the publishing principal." }, { "$ref": "#/components/schemas/AgentOutputSourceJSON" } ] }, "stale_checked_at": { "format": "date-time", "type": [ "string", "null" ] }, "stale_checked_code_version_id": { "type": [ "string", "null" ] }, "stale_outcome": { "type": "string" }, "status": { "type": "string" }, "status_actor_display_name": { "type": [ "string", "null" ] }, "status_actor_id": { "type": [ "string", "null" ] }, "status_actor_identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "status_actor_kind": { "type": [ "string", "null" ] }, "status_changed_at": { "format": "date-time", "type": [ "string", "null" ] }, "status_reason": { "type": [ "string", "null" ] }, "status_source": { "type": [ "string", "null" ] }, "trail_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "discussion_id", "discussion_message_count", "id", "trail_id", "repo_id", "review_id", "code_version_id", "actor_id", "actor_display_name", "actor_identity", "body", "severity", "confidence", "status", "status_reason", "status_actor_id", "status_actor_display_name", "status_actor_identity", "status_changed_at", "status_source", "status_actor_kind", "stale_outcome", "stale_checked_at", "stale_checked_code_version_id", "client_id", "client_id_hash", "created_at", "updated_at", "location" ], "type": "object" }, "ReviewCommentLinkJSON": { "additionalProperties": false, "properties": { "link_type": { "type": "string" }, "source_comment_id": { "type": "string" }, "target_comment_id": { "type": "string" } }, "required": [ "source_comment_id", "target_comment_id", "link_type" ], "type": "object" }, "ReviewCommentLocationInputJSON": { "additionalProperties": false, "properties": { "end_column": { "format": "int64", "type": "integer" }, "end_line": { "format": "int64", "type": "integer" }, "file_path": { "type": "string" }, "granularity": { "enum": [ "line", "range", "file", "whole_change" ], "type": "string" }, "language": { "type": "string" }, "nearby_text": { "type": "string" }, "selected_text": { "type": "string" }, "start_column": { "format": "int64", "type": "integer" }, "start_line": { "format": "int64", "type": "integer" } }, "required": [ "granularity" ], "type": "object" }, "ReviewCommentPatchRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewCommentPatchRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": { "maxLength": 65536, "type": [ "string", "null" ] }, "confidence": { "format": "double", "maximum": 1, "minimum": 0, "type": [ "number", "null" ] }, "severity": { "enum": [ "high", "medium", "low" ], "type": [ "string", "null" ] }, "status": { "enum": [ "open", "resolved", "dismissed" ], "type": "string" }, "status_reason": { "type": [ "string", "null" ] } }, "type": "object" }, "ReviewCommentsAtomicResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewCommentsAtomicResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ReviewCommentBatchResultJSON" }, "type": [ "array", "null" ] }, "review": { "$ref": "#/components/schemas/ReviewCommentsAtomicReviewJSON" } }, "required": [ "review", "results" ], "type": "object" }, "ReviewCommentsAtomicReviewJSON": { "additionalProperties": false, "properties": { "actor_id": { "type": [ "string", "null" ] }, "actor_is_service": { "type": "boolean" }, "code_version_id": { "type": "string" }, "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "started_at": { "format": "date-time", "type": "string" }, "summary": { "type": [ "string", "null" ] }, "trail_id": { "type": "string" } }, "required": [ "id", "trail_id", "code_version_id", "actor_id", "actor_is_service", "summary", "started_at", "completed_at" ], "type": "object" }, "ReviewCommentsBatchResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewCommentsBatchResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ReviewCommentBatchResultJSON" }, "type": [ "array", "null" ] } }, "required": [ "results" ], "type": "object" }, "ReviewCommentsPage": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewCommentsPage.json" ], "format": "uri", "readOnly": true, "type": "string" }, "comments": { "items": { "$ref": "#/components/schemas/ReviewCommentJSON" }, "type": [ "array", "null" ] }, "event_cursor": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "comments", "event_cursor" ], "type": "object" }, "ReviewCommentsRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewCommentsRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "comments": { "items": { "$ref": "#/components/schemas/ReviewCommentBatchRequestJSON" }, "maxItems": 100, "type": [ "array", "null" ] }, "summary": { "type": [ "string", "null" ] } }, "type": "object" }, "ReviewDiffFileJSON": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "deletions": { "format": "int64", "type": "integer" }, "patch": { "type": [ "string", "null" ] }, "patch_truncated": { "type": "boolean" }, "path": { "type": "string" }, "previous_path": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "path", "previous_path", "status", "additions", "deletions", "patch", "patch_truncated" ], "type": "object" }, "ReviewDiffResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewDiffResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "base_sha": { "type": [ "string", "null" ] }, "code_version_id": { "type": "string" }, "files": { "items": { "$ref": "#/components/schemas/ReviewDiffFileJSON" }, "type": [ "array", "null" ] }, "head_sha": { "type": [ "string", "null" ] } }, "required": [ "code_version_id", "base_sha", "head_sha", "files" ], "type": "object" }, "ReviewEventJSON": { "additionalProperties": false, "properties": { "actor_id": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "event_type": { "description": "Open event type. Periods separate domains; each segment uses lowercase snake_case. Unknown future names must be tolerated.", "type": "string", "x-open-enum": [ "code_version.created", "review.started", "comment.created", "comment.updated", "comment.status_changed", "comment.stale_checked", "suggested_change.created", "gate.updated", "monitor.updated", "agent.updated", "runner.run", "runner.status", "runner.done", "runner.error" ] }, "id": { "type": "string" }, "payload": {}, "review_id": { "type": [ "string", "null" ] }, "target_id": { "type": "string" }, "target_type": { "type": "string" }, "trail_id": { "type": "string" } }, "required": [ "id", "trail_id", "review_id", "actor_id", "event_type", "target_type", "target_id", "payload", "created_at" ], "type": "object" }, "ReviewEventsResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewEventsResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/ReviewEventJSON" }, "type": [ "array", "null" ] }, "next_cursor": { "type": "string" } }, "required": [ "events" ], "type": "object" }, "ReviewFilesResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewFilesResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "code_version_id": { "type": "string" }, "files": { "additionalProperties": { "type": [ "string", "null" ] }, "type": "object" }, "head_sha": { "type": [ "string", "null" ] } }, "required": [ "code_version_id", "head_sha", "files" ], "type": "object" }, "ReviewJSON": { "additionalProperties": false, "properties": { "actor_id": { "type": [ "string", "null" ] }, "code_version_id": { "type": "string" }, "id": { "type": "string" }, "source_execution_id": { "description": "The execution whose Review changes result this review publishes; null for reviews not published by a saved Agent's mode.", "type": [ "string", "null" ] }, "started_at": { "format": "date-time", "type": "string" }, "summary": { "type": [ "string", "null" ] }, "trail_id": { "type": "string" } }, "required": [ "id", "trail_id", "code_version_id", "actor_id", "summary", "started_at", "source_execution_id" ], "type": "object" }, "ReviewLimitsJSON": { "additionalProperties": false, "properties": { "max_comments_per_batch": { "format": "int64", "type": "integer" } }, "required": [ "max_comments_per_batch" ], "type": "object" }, "ReviewRerunBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewRerunBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "launched": { "format": "int64", "type": "integer" } }, "required": [ "launched" ], "type": "object" }, "ReviewSnapshotCountsJSON": { "additionalProperties": false, "properties": { "dismissed": { "format": "int64", "type": "integer" }, "open": { "format": "int64", "type": "integer" }, "resolved": { "format": "int64", "type": "integer" }, "stale": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "open", "resolved", "dismissed", "stale", "total" ], "type": "object" }, "ReviewSnapshotResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewSnapshotResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "code_version": { "$ref": "#/components/schemas/CodeVersionJSON" }, "comments": { "items": { "$ref": "#/components/schemas/SnapshotCommentJSON" }, "type": [ "array", "null" ] }, "counts": { "$ref": "#/components/schemas/ReviewSnapshotCountsJSON" }, "event_cursor": { "type": "string" }, "next_cursor": { "type": "string" }, "review": { "$ref": "#/components/schemas/ReviewJSON" } }, "required": [ "review", "code_version", "counts", "comments", "event_cursor" ], "type": "object" }, "ReviewStartRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/ReviewStartRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "actor_id": { "pattern": "^agent:[a-zA-Z0-9_-]{1,64}$", "type": "string" }, "base_ref": { "maxLength": 255, "type": "string" }, "base_sha": { "pattern": "^[a-fA-F0-9]{40}$", "type": [ "string", "null" ] }, "head_ref": { "maxLength": 255, "type": "string" }, "head_sha": { "pattern": "^[a-fA-F0-9]{40}$", "type": [ "string", "null" ] } }, "type": "object" }, "ReviewSuggestedChangeInputJSON": { "additionalProperties": false, "properties": { "change_type": { "enum": [ "unified_diff", "file_replacement", "json_patch", "manual_instruction" ], "type": "string" }, "expected_end_line": { "format": "int64", "type": "integer" }, "expected_file_hash": { "type": "string" }, "expected_file_path": { "type": "string" }, "expected_lines": { "type": "string" }, "expected_start_line": { "format": "int64", "type": "integer" }, "instruction": { "type": "string" }, "patch": { "type": "string" } }, "required": [ "change_type" ], "type": "object" }, "Run": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/Run.json" ], "format": "uri", "readOnly": true, "type": "string" }, "actor": { "$ref": "#/components/schemas/ConfigActor" }, "agent": { "$ref": "#/components/schemas/RunAgent" }, "attempt": { "format": "int64", "type": "integer" }, "billing_subject": { "allOf": [ { "description": "The subject that pays for the run, as recorded when it launched; null for runs launched before subjects were recorded, and for a caller who reads only the project's repositories." }, { "$ref": "#/components/schemas/BillingSubjectRef" } ] }, "created_at": { "format": "date-time", "type": "string" }, "diagnostic": { "description": "Credential-redacted process-output tail for a failed run, at most 4096 UTF-8 bytes including any truncation marker; null when unavailable. May contain repository content. Not a complete log.", "maxLength": 4096, "type": [ "string", "null" ] }, "dispatch": { "$ref": "#/components/schemas/RunDispatch" }, "environment": { "$ref": "#/components/schemas/RunVersionRef" }, "error": { "allOf": [ { "description": "Why the run failed or timed out, or why Entire canceled it (its agent was paused or archived, or its branch advanced); null otherwise, including for a run canceled through the cancel route." }, { "$ref": "#/components/schemas/RunError" } ] }, "events": { "items": { "$ref": "#/components/schemas/RunEvent" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "mode": { "$ref": "#/components/schemas/RunMode" }, "output": { "$ref": "#/components/schemas/RunOutput" }, "preset": { "allOf": [ { "description": "The Entire preset the run ran, at the version and content it pinned; null for a custom agent's run." }, { "$ref": "#/components/schemas/RunPreset" } ] }, "project_id": { "type": "string" }, "replayed": { "description": "On a start or retry: true when the Idempotency-Key named an earlier identical request, whose run is returned.", "type": "boolean" }, "repository_id": { "type": "string" }, "result": { "$ref": "#/components/schemas/RunResult" }, "retry_of": { "type": [ "string", "null" ] }, "review_changes_result": { "allOf": [ { "description": "A completed run's review result; null otherwise." }, { "$ref": "#/components/schemas/RunReviewChangesResult" } ] }, "runtime": { "$ref": "#/components/schemas/RunRuntime" }, "status": { "description": "The run's status: queued (waiting for a sandbox), running, succeeded, failed, timed_out or canceled.", "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" }, "target": { "$ref": "#/components/schemas/RunTarget" }, "trigger": { "$ref": "#/components/schemas/RunTrigger" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_by_model": { "description": "Token usage the agent reported, as usageByModel on the runner runs' routes; null until the first report. One entry with the run's unsplit total until runs record a per-model split. Price an entry at its model's rate only when model is set; a null model means an unsplit total across several models or unavailable model attribution.", "items": { "$ref": "#/components/schemas/RunModelUsage" }, "type": [ "array", "null" ] } }, "required": [ "id", "project_id", "repository_id", "status", "error", "diagnostic", "billing_subject", "agent", "environment", "trigger", "target", "runtime", "preset", "actor", "attempt", "retry_of", "dispatch", "result", "mode", "review_changes_result", "output", "usage_by_model", "events", "created_at", "updated_at" ], "type": "object" }, "RunAgent": { "additionalProperties": false, "properties": { "id": { "description": "Agent id (GET .../agents/{id}).", "type": "string" }, "name": { "description": "The agent's name as the run pinned it.", "type": "string" }, "version": { "description": "The agent version the run pinned.", "format": "int64", "type": "integer" } }, "required": [ "id", "version", "name" ], "type": "object" }, "RunAutomationResultJSON": { "additionalProperties": false, "properties": { "automation": { "type": "string" }, "createdAt": { "type": "string" }, "data": {}, "resultType": { "type": "string" } }, "required": [ "automation", "resultType", "data", "createdAt" ], "type": "object" }, "RunCreate": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RunCreate.json" ], "format": "uri", "readOnly": true, "type": "string" }, "head_sha": { "description": "Optional commit pin: the run is refused (409) if the Change's head is no longer this commit.", "type": "string" }, "target": { "$ref": "#/components/schemas/RunTargetInput" } }, "required": [ "target" ], "type": "object" }, "RunDetailResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RunDetailResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "automationResult": { "$ref": "#/components/schemas/RunAutomationResultJSON" }, "events": { "items": { "$ref": "#/components/schemas/RunEventJSON" }, "type": [ "array", "null" ] }, "prompts": { "items": { "$ref": "#/components/schemas/RunPromptJSON" }, "type": [ "array", "null" ] }, "run": { "$ref": "#/components/schemas/RunDetailRunJSON" } }, "required": [ "run", "prompts", "events", "automationResult" ], "type": "object" }, "RunDetailRunJSON": { "additionalProperties": false, "properties": { "extraArgs": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "model": { "description": "Model the runner config requested; null when it set none. See usageByModel and modelsUsed for what ran.", "type": [ "string", "null" ] }, "scopeJson": {} }, "required": [ "model", "extraArgs", "scopeJson" ], "type": "object" }, "RunDispatch": { "additionalProperties": false, "properties": { "attempts": { "format": "int64", "type": "integer" }, "next_attempt_at": { "description": "When a pending dispatch is next attempted.", "format": "date-time", "type": [ "string", "null" ] }, "published_at": { "format": "date-time", "type": [ "string", "null" ] }, "state": { "enum": [ "pending", "published", "refused", "abandoned" ], "type": "string" } }, "required": [ "state", "attempts", "next_attempt_at", "published_at" ], "type": "object" }, "RunError": { "additionalProperties": false, "properties": { "code": { "description": "Set when the run was refused for billing: billing_trial_ended, billing_credit_exhausted, billing_over_limit, billing_blocked or billing_not_enrolled; null otherwise.", "type": [ "string", "null" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "RunEvent": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "detail": { "type": "string" }, "kind": { "type": "string" }, "type": { "type": "string" } }, "required": [ "kind", "type", "detail", "created_at" ], "type": "object" }, "RunEventJSON": { "additionalProperties": false, "properties": { "createdAt": { "type": "string" }, "cursor": { "format": "int64", "type": "integer" }, "detail": { "type": "string" }, "kind": { "type": "string" }, "type": { "type": "string" } }, "required": [ "cursor", "kind", "type", "detail", "createdAt" ], "type": "object" }, "RunFinding": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "confidence": { "format": "double", "type": "number" }, "location": { "$ref": "#/components/schemas/RunFindingLocation" }, "severity": { "enum": [ "high", "medium", "low" ], "type": "string" } }, "required": [ "body", "severity", "confidence", "location" ], "type": "object" }, "RunFindingLocation": { "additionalProperties": false, "properties": { "end_line": { "format": "int64", "type": [ "integer", "null" ] }, "file_path": { "type": "string" }, "granularity": { "enum": [ "line", "range", "file" ], "type": "string" }, "start_line": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "granularity", "file_path", "start_line", "end_line" ], "type": "object" }, "RunListItemJSON": { "additionalProperties": false, "properties": { "agent": { "type": [ "string", "null" ] }, "automation": { "type": [ "string", "null" ] }, "billingSubject": { "allOf": [ { "description": "The subject that pays for the run, as recorded when it launched; null for runs launched before subjects were recorded." }, { "$ref": "#/components/schemas/BillingSubjectRef" } ] }, "createdAt": { "type": "string" }, "credentialSource": { "type": "string" }, "errorCode": { "description": "Set when the run was refused for billing: billing_trial_ended, billing_credit_exhausted, billing_over_limit, billing_blocked or billing_not_enrolled.", "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "headSha": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "modelsUsed": { "description": "Every model the run billed, including subagent and background models; null when the stream named none.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "promptStartedAt": { "type": [ "string", "null" ] }, "provisionStartedAt": { "type": [ "string", "null" ] }, "queuedAt": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "trail": { "$ref": "#/components/schemas/RunListTrailJSON" }, "updatedAt": { "type": "string" }, "usageByModel": { "description": "Token usage the agent reported; null until the first report. Runs do not record a per-model split yet, so the list currently holds one entry with the run's unsplit total. Price an entry at its model's rate only when model is set; a null model means an unsplit total across several models or unavailable model attribution.", "items": { "$ref": "#/components/schemas/RunModelUsageJSON" }, "type": [ "array", "null" ] } }, "required": [ "id", "status", "automation", "agent", "ref", "errorMessage", "errorCode", "billingSubject", "headSha", "createdAt", "updatedAt", "queuedAt", "provisionStartedAt", "promptStartedAt", "trail", "usageByModel", "modelsUsed" ], "type": "object" }, "RunListTrailJSON": { "additionalProperties": false, "properties": { "branch": { "type": "string" }, "id": { "type": "string" }, "number": { "format": "int64", "type": "integer" }, "title": { "type": "string" } }, "required": [ "id", "number", "title", "branch" ], "type": "object" }, "RunMode": { "additionalProperties": false, "properties": { "contract_version": { "type": "string" }, "kind": { "enum": [ "review" ], "type": "string" }, "output_mode": { "enum": [ "claude_json_schema", "codex_output_schema" ], "type": "string" }, "output_schema_sha256": { "description": "SHA-256 of the exact output schema the harness was given (full schema in the snapshot).", "type": "string" }, "reviewed": { "$ref": "#/components/schemas/RunModeCommits" }, "signal": { "allOf": [ { "description": "The signal descriptor the run reports, as the run pinned it." }, { "$ref": "#/components/schemas/AgentSignal" } ] } }, "required": [ "kind", "contract_version", "output_mode", "output_schema_sha256", "signal", "reviewed" ], "type": "object" }, "RunModeCommits": { "additionalProperties": false, "properties": { "base_sha": { "description": "The base branch's commit at admission.", "type": "string" }, "diff_base_sha": { "description": "The merge base the diff was taken against, and the published review's base anchor.", "type": "string" }, "head_sha": { "type": "string" } }, "required": [ "head_sha", "base_sha", "diff_base_sha" ], "type": "object" }, "RunModelUsage": { "additionalProperties": false, "properties": { "cache_creation_tokens": { "description": "Cache writes, all TTLs combined.", "format": "int64", "type": "integer" }, "cache_read_tokens": { "format": "int64", "type": "integer" }, "input_tokens": { "format": "int64", "type": "integer" }, "model": { "description": "Model these tokens are attributed to; null for an unsplit total across several models or when model attribution is unavailable.", "type": [ "string", "null" ] }, "output_tokens": { "format": "int64", "type": "integer" } }, "required": [ "model", "input_tokens", "output_tokens", "cache_creation_tokens", "cache_read_tokens" ], "type": "object" }, "RunModelUsageJSON": { "additionalProperties": false, "properties": { "cacheCreationTokens": { "description": "Cache writes, all TTLs combined.", "format": "int64", "type": "integer" }, "cacheReadTokens": { "format": "int64", "type": "integer" }, "inputTokens": { "format": "int64", "type": "integer" }, "model": { "description": "Model these tokens are attributed to; null for an unsplit total across several models or when model attribution is unavailable.", "type": [ "string", "null" ] }, "outputTokens": { "format": "int64", "type": "integer" } }, "required": [ "model", "inputTokens", "outputTokens", "cacheCreationTokens", "cacheReadTokens" ], "type": "object" }, "RunOutput": { "additionalProperties": false, "properties": { "text": { "type": [ "string", "null" ] }, "truncated": { "type": "boolean" } }, "required": [ "text", "truncated" ], "type": "object" }, "RunPreset": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "sha256": { "description": "SHA-256 of the preset content the run ran; null for a run admitted before presets were versioned.", "type": [ "string", "null" ] }, "version": { "description": "The preset version the run ran; null for a run admitted before presets were versioned.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "version", "sha256" ], "type": "object" }, "RunPriorFinding": { "additionalProperties": false, "properties": { "evidence": { "type": "string" }, "finding_id": { "description": "The review comment the verdict is on.", "type": "string" }, "outcome": { "description": "What the server did with it (see the finding's agent_verdict); null once the finding is deleted.", "enum": [ "resolved", "dismissed", "kept", "awaiting_confirmation", "reopened_by_person", "already_closed" ], "type": [ "string", "null" ] }, "verdict": { "enum": [ "fixed", "still_present", "no_longer_applies" ], "type": "string" } }, "required": [ "finding_id", "verdict", "evidence", "outcome" ], "type": "object" }, "RunPromptJSON": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "prompt": { "type": [ "string", "null" ] }, "queuedAt": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "prompt", "queuedAt" ], "type": "object" }, "RunResult": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "data": {}, "result_type": { "type": "string" } }, "required": [ "result_type", "data", "created_at" ], "type": "object" }, "RunReviewChangesResult": { "additionalProperties": false, "properties": { "findings": { "items": { "$ref": "#/components/schemas/RunFinding" }, "type": [ "array", "null" ] }, "prior_findings": { "description": "The run's verdicts on its agent's earlier open findings, one each.", "items": { "$ref": "#/components/schemas/RunPriorFinding" }, "type": [ "array", "null" ] }, "review_id": { "description": "The Trail review that published the findings (GET the review snapshot to see their status); null only if the link is unreadable.", "type": [ "string", "null" ] }, "signal": { "$ref": "#/components/schemas/RunSignalReading" }, "summary": { "description": "The review as a whole; null for a result from before summaries.", "type": [ "string", "null" ] } }, "required": [ "summary", "signal", "findings", "prior_findings", "review_id" ], "type": "object" }, "RunRuntime": { "additionalProperties": false, "properties": { "auto_stop_minutes": { "format": "int64", "type": [ "integer", "null" ] }, "checkout": { "type": "string" }, "git_access": { "type": "string" }, "harness": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "provider": { "description": "Sandbox provider recorded on older runs; absent on new ones. Runners ignore it.", "type": "string" }, "reasoning_effort": { "type": [ "string", "null" ] }, "timeout_ms": { "format": "int64", "type": "integer" } }, "required": [ "harness", "model", "reasoning_effort", "timeout_ms", "checkout", "git_access", "auto_stop_minutes" ], "type": "object" }, "RunSignalReading": { "additionalProperties": false, "properties": { "polarity": { "description": "Which readings are good.", "enum": [ "higher_is_better", "lower_is_better", "neutral" ], "type": "string" }, "rationale": { "type": "string" }, "value": { "description": "boolean, integer 0-100, or small/medium/large, per value_type." }, "value_type": { "description": "boolean (true/false), percent (0-100) or size (small, medium, large).", "enum": [ "boolean", "percent", "size" ], "type": "string" } }, "required": [ "value", "rationale", "value_type", "polarity" ], "type": "object" }, "RunSummary": { "additionalProperties": false, "properties": { "actor": { "$ref": "#/components/schemas/ConfigActor" }, "agent": { "$ref": "#/components/schemas/RunAgent" }, "attempt": { "format": "int64", "type": "integer" }, "billing_subject": { "allOf": [ { "description": "The subject that pays for the run, as recorded when it launched; null for runs launched before subjects were recorded, and for a caller who reads only the project's repositories." }, { "$ref": "#/components/schemas/BillingSubjectRef" } ] }, "change_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "dispatch_state": { "type": [ "string", "null" ] }, "environment": { "$ref": "#/components/schemas/RunVersionRef" }, "error": { "allOf": [ { "description": "Why the run failed or timed out, or why Entire canceled it (its agent was paused or archived, or its branch advanced); null otherwise, including for a run canceled through the cancel route." }, { "$ref": "#/components/schemas/RunError" } ] }, "id": { "type": "string" }, "project_id": { "type": "string" }, "repository_id": { "type": "string" }, "retry_of": { "type": [ "string", "null" ] }, "status": { "description": "The run's status: queued (waiting for a sandbox), running, succeeded, failed, timed_out or canceled.", "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" }, "trail_id": { "type": "string" }, "trigger": { "$ref": "#/components/schemas/RunTrigger" }, "updated_at": { "format": "date-time", "type": "string" }, "usage_by_model": { "description": "Token usage the agent reported, as usageByModel on the runner runs' routes; null until the first report. One entry with the run's unsplit total until runs record a per-model split. Price an entry at its model's rate only when model is set; a null model means an unsplit total across several models or unavailable model attribution.", "items": { "$ref": "#/components/schemas/RunModelUsage" }, "type": [ "array", "null" ] } }, "required": [ "id", "project_id", "repository_id", "status", "error", "billing_subject", "dispatch_state", "agent", "environment", "trigger", "trail_id", "change_id", "actor", "attempt", "retry_of", "usage_by_model", "created_at", "updated_at" ], "type": "object" }, "RunTarget": { "additionalProperties": false, "properties": { "base_ref": { "type": "string" }, "base_sha": { "type": "string" }, "change_id": { "type": "string" }, "head_sha": { "type": "string" }, "ref": { "description": "The Change's branch.", "type": "string" }, "repository_id": { "type": "string" }, "trail_id": { "type": "string" } }, "required": [ "repository_id", "trail_id", "change_id", "ref", "head_sha", "base_ref", "base_sha" ], "type": "object" }, "RunTargetInput": { "additionalProperties": false, "properties": { "change_id": { "description": "One of the Trail's Changes (ULID). A Trail may hold several Changes, so the Change is always named; its repository is the run's.", "type": "string" }, "trail_id": { "description": "A product Trail of the project (ULID).", "type": "string" } }, "required": [ "trail_id", "change_id" ], "type": "object" }, "RunTrigger": { "additionalProperties": false, "properties": { "id": { "description": "The agent trigger's id for a push run; null otherwise.", "type": [ "string", "null" ] }, "kind": { "description": "push: the agent's push trigger, on a push to a Trail branch or when a Trail there opens or is marked ready; manual: a POST .../runs; retry: a POST .../runs/{id}/retry of an earlier run.", "enum": [ "push", "manual", "retry" ], "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "RunVersionRef": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "version" ], "type": "object" }, "RunnerResultJSON": { "additionalProperties": false, "properties": { "adapter": { "type": "string" }, "data": {}, "type": { "type": "string" } }, "required": [ "type", "adapter", "data" ], "type": "object" }, "RunnerRunJSON": { "additionalProperties": false, "properties": { "createdAt": { "type": "string" }, "errorMessage": { "type": [ "string", "null" ] }, "headSha": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "promptStatus": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "createdAt", "updatedAt", "errorMessage", "promptStatus", "headSha" ], "type": "object" }, "RunnerSettingsBody": { "additionalProperties": false, "properties": { "auto_run_on_push": { "type": "boolean" }, "runners_enabled": { "type": "boolean" } }, "required": [ "runners_enabled", "auto_run_on_push" ], "type": "object" }, "RunnerSettingsInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RunnerSettingsInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "auto_run_on_push": { "type": "boolean" }, "runners_enabled": { "type": "boolean" } }, "type": "object" }, "RunnerSettingsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RunnerSettingsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "settings": { "$ref": "#/components/schemas/RunnerSettingsBody" } }, "required": [ "settings" ], "type": "object" }, "RunsListResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/RunsListResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/RunListItemJSON" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": [ "string", "null" ] } }, "required": [ "items", "nextPageToken" ], "type": "object" }, "SavedFilterTab": { "additionalProperties": false, "properties": { "displaySettings": { "additionalProperties": { "type": "string" }, "type": "object" }, "filterOrder": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "filters": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "filters", "filterOrder" ], "type": "object" }, "SessionAttribution": { "additionalProperties": false, "properties": { "agentLines": { "format": "int64", "type": "integer" }, "agentPercentage": { "format": "double", "type": "number" }, "calculatedAt": { "type": "string" }, "humanAdded": { "format": "int64", "type": "integer" }, "humanModified": { "format": "int64", "type": "integer" }, "humanRemoved": { "format": "int64", "type": "integer" }, "totalCommitted": { "format": "int64", "type": "integer" } }, "required": [ "calculatedAt", "agentLines", "humanAdded", "humanModified", "humanRemoved", "totalCommitted", "agentPercentage" ], "type": "object" }, "SessionDetailFilters": { "additionalProperties": false, "properties": { "checkpoints": { "type": "boolean" }, "intermediateSteps": { "type": "boolean" }, "prompts": { "type": "boolean" }, "responses": { "type": "boolean" }, "toolCalls": { "type": "boolean" }, "toolCategories": { "additionalProperties": { "type": "boolean" }, "type": "object" } }, "required": [ "prompts", "responses", "intermediateSteps", "checkpoints", "toolCalls", "toolCategories" ], "type": "object" }, "SessionDetailFiltersResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionDetailFiltersResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "filters": { "$ref": "#/components/schemas/SessionDetailFilters" }, "showHiddenIndicators": { "type": [ "boolean", "null" ] } }, "required": [ "filters", "showHiddenIndicators" ], "type": "object" }, "SessionDetailPreference": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionDetailPreference.json" ], "format": "uri", "readOnly": true, "type": "string" }, "filters": { "$ref": "#/components/schemas/SessionDetailFilters" }, "showHiddenIndicators": { "type": "boolean" } }, "required": [ "filters", "showHiddenIndicators" ], "type": "object" }, "SessionEnvelopeCheckpoint": { "additionalProperties": false, "properties": { "additions": { "format": "int64", "type": "integer" }, "authorUsername": { "type": "string" }, "checkpointId": { "type": "string" }, "commitSha": { "type": "string" }, "deletions": { "format": "int64", "type": "integer" }, "filesChanged": { "format": "int64", "type": "integer" }, "message": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "checkpointId", "commitSha", "message", "additions", "deletions", "filesChanged", "timestamp" ], "type": "object" }, "SessionFacetOption": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "value", "label" ], "type": "object" }, "SessionListFacets": { "additionalProperties": false, "properties": { "agents": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "authors": { "items": { "$ref": "#/components/schemas/SessionFacetOption" }, "type": [ "array", "null" ] }, "models": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "authors", "agents", "models" ], "type": "object" }, "SessionListItem": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionListItem.json" ], "format": "uri", "readOnly": true, "type": "string" }, "agent": { "type": [ "string", "null" ] }, "attributionAgentLines": { "format": "int64", "type": [ "integer", "null" ] }, "attributionCalculatedAt": { "type": [ "string", "null" ] }, "attributionHumanAdded": { "format": "int64", "type": [ "integer", "null" ] }, "attributionHumanModified": { "format": "int64", "type": [ "integer", "null" ] }, "attributionHumanRemoved": { "format": "int64", "type": [ "integer", "null" ] }, "attributionTotalCommitted": { "format": "int64", "type": [ "integer", "null" ] }, "cacheCreationTokens": { "format": "int64", "type": [ "integer", "null" ] }, "cacheReadTokens": { "format": "int64", "type": [ "integer", "null" ] }, "checkpointCount": { "format": "int64", "type": "integer" }, "customName": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "firstCommitAuthorAvatarUrl": { "type": "string" }, "firstCommitAuthorUsername": { "type": [ "string", "null" ] }, "inputTokens": { "format": "int64", "type": [ "integer", "null" ] }, "isPublic": { "type": "boolean" }, "kind": { "type": [ "string", "null" ] }, "lastActivityAt": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "outputTokens": { "format": "int64", "type": [ "integer", "null" ] }, "prompt": { "type": [ "string", "null" ] }, "sessionId": { "type": "string" }, "startedAt": { "type": "string" }, "stepCount": { "format": "int64", "type": "integer" }, "subagentCount": { "format": "int64", "type": "integer" } }, "required": [ "sessionId", "displayName", "customName", "isPublic", "agent", "model", "kind", "prompt", "firstCommitAuthorUsername", "startedAt", "lastActivityAt", "checkpointCount", "subagentCount", "stepCount", "inputTokens", "outputTokens", "cacheCreationTokens", "cacheReadTokens", "attributionAgentLines", "attributionHumanAdded", "attributionHumanModified", "attributionHumanRemoved", "attributionTotalCommitted", "attributionCalculatedAt" ], "type": "object" }, "SessionMeta": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "checkpointCount": { "format": "int64", "type": "integer" }, "createdAt": { "type": "string" }, "customName": { "type": "string" }, "displayName": { "type": "string" }, "isPublic": { "type": "boolean" }, "model": { "type": "string" }, "prompt": { "type": "string" }, "shareId": { "type": "string" }, "steps": { "format": "int64", "type": "integer" } }, "required": [ "agent", "displayName", "steps", "checkpointCount", "isPublic" ], "type": "object" }, "SessionNamesBatchRepoRefs": { "additionalProperties": false, "properties": { "repoId": { "description": "Code repo id (ULID)", "pattern": "^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$", "type": "string" }, "sessionIds": { "description": "Session ids to resolve under this repo", "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "repoId", "sessionIds" ], "type": "object" }, "SessionNamesBatchResolveInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionNamesBatchResolveInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "include": { "description": "Extra data to include; \"rows\" adds full session list items", "items": { "enum": [ "rows" ], "type": "string" }, "type": [ "array", "null" ] }, "repos": { "description": "Repo groups to resolve; the total session ids across groups is capped at 500", "items": { "$ref": "#/components/schemas/SessionNamesBatchRepoRefs" }, "maxItems": 500, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "repos" ], "type": "object" }, "SessionNamesBatchResolveOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionNamesBatchResolveOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "repos": { "additionalProperties": { "$ref": "#/components/schemas/SessionNamesResolveResult" }, "type": "object" } }, "required": [ "repos" ], "type": "object" }, "SessionNamesResolveInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionNamesResolveInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "include": { "description": "Extra data to include; \"rows\" adds full session list items", "items": { "enum": [ "rows" ], "type": "string" }, "type": [ "array", "null" ] }, "sessionIds": { "description": "Session ids to resolve", "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "sessionIds" ], "type": "object" }, "SessionNamesResolveResult": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionNamesResolveResult.json" ], "format": "uri", "readOnly": true, "type": "string" }, "codeRepoFullName": { "type": "string" }, "names": { "additionalProperties": { "type": "string" }, "type": "object" }, "sessions": { "additionalProperties": { "$ref": "#/components/schemas/SessionListItem" }, "type": "object" } }, "required": [ "names" ], "type": "object" }, "SessionPatternDepthItem": { "additionalProperties": false, "properties": { "bucket": { "type": "string" }, "count": { "format": "int64", "type": "integer" } }, "required": [ "bucket", "count" ], "type": "object" }, "SessionPatternHourItem": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "hour": { "format": "int64", "type": "integer" } }, "required": [ "hour", "count" ], "type": "object" }, "SessionPatternVelocityItem": { "additionalProperties": false, "properties": { "avgSteps": { "format": "double", "type": "number" }, "date": { "type": "string" } }, "required": [ "date", "avgSteps" ], "type": "object" }, "SessionPatternWeekdayItem": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "day": { "format": "int64", "type": "integer" } }, "required": [ "day", "count" ], "type": "object" }, "SessionRenameInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionRenameInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "displayName": { "description": "New custom name; null clears the override", "maxLength": 200, "type": [ "string", "null" ] } }, "required": [ "displayName" ], "type": "object" }, "SessionRenameOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionRenameOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "displayName": { "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "SessionRepoMeta": { "additionalProperties": false, "properties": { "defaultBranch": { "type": "string" }, "fullName": { "type": "string" }, "isPrivate": { "type": "boolean" }, "name": { "type": "string" }, "owner": { "type": "string" }, "publicSharingEnabled": { "type": "boolean" }, "shareToggleApplicable": { "type": "boolean" } }, "required": [ "owner", "name", "fullName", "defaultBranch", "isPrivate", "publicSharingEnabled", "shareToggleApplicable" ], "type": "object" }, "SessionShareOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionShareOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "isPublic": { "type": "boolean" }, "shareId": { "type": "string" }, "sharePath": { "type": "string" } }, "required": [ "isPublic" ], "type": "object" }, "SessionSubagentTranscriptOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionSubagentTranscriptOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "handback": { "allOf": [ { "description": "the report the subagent returned to its parent; null when none was recorded" }, { "$ref": "#/components/schemas/SubagentHandback" } ] }, "handbackIncomplete": { "description": "true when Codex handback resolution is incomplete: parent capture unreadable or clipped, or child identity could not be joined; may be true even when handback is null", "type": "boolean" }, "handbackMessages": { "description": "every message the subagent sent its parent, oldest first (Codex); empty when the provider records only the final report", "items": { "$ref": "#/components/schemas/SubagentHandbackMessage" }, "type": [ "array", "null" ] }, "model": { "description": "provider-recorded model of the subagent transcript; null when the provider format does not record one", "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/SubagentSummaryItem" }, "transcript": { "$ref": "#/components/schemas/SessionTranscript" } }, "required": [ "summary", "model", "transcript", "handback", "handbackMessages", "handbackIncomplete" ], "type": "object" }, "SessionSubagentsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionSubagentsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "sessionId": { "type": "string" }, "subagents": { "items": { "$ref": "#/components/schemas/SubagentSummaryItem" }, "type": [ "array", "null" ] } }, "required": [ "sessionId", "subagents", "nextCursor" ], "type": "object" }, "SessionTokenUsage": { "additionalProperties": false, "properties": { "inputTokens": { "format": "int64", "type": "integer" }, "outputTokens": { "format": "int64", "type": "integer" } }, "required": [ "inputTokens", "outputTokens" ], "type": "object" }, "SessionTranscript": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "attribution": { "$ref": "#/components/schemas/SessionAttribution" }, "checkpointTranscriptStart": { "format": "int64", "type": [ "integer", "null" ] }, "messages": { "items": { "$ref": "#/components/schemas/TranscriptMessage" }, "type": [ "array", "null" ] }, "parsingFallback": { "type": "boolean" }, "parsingWarning": { "type": "string" }, "sessionId": { "type": "string" }, "skillEvents": { "items": { "$ref": "#/components/schemas/SkillEvent" }, "type": [ "array", "null" ] }, "tokenUsage": { "$ref": "#/components/schemas/SessionTokenUsage" }, "transcriptIdentifierAtStart": { "type": [ "string", "null" ] } }, "required": [ "sessionId", "agent", "messages", "transcriptIdentifierAtStart", "checkpointTranscriptStart" ], "type": "object" }, "SessionTranscriptOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/SessionTranscriptOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "checkpoints": { "items": { "$ref": "#/components/schemas/SessionEnvelopeCheckpoint" }, "type": [ "array", "null" ] }, "from_cache": { "type": "boolean" }, "repo": { "$ref": "#/components/schemas/SessionRepoMeta" }, "session": { "$ref": "#/components/schemas/SessionMeta" }, "sessionId": { "type": "string" }, "sessions": { "items": { "$ref": "#/components/schemas/SessionTranscript" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "tokenUsage": { "$ref": "#/components/schemas/SessionTokenUsage" }, "viewer": { "$ref": "#/components/schemas/SessionViewer" } }, "required": [ "status", "sessionId", "sessions", "from_cache", "repo", "session", "checkpoints", "tokenUsage", "viewer" ], "type": "object" }, "SessionViewer": { "additionalProperties": false, "properties": { "canEdit": { "type": "boolean" }, "canSeeCheckpointData": { "type": "boolean" } }, "required": [ "canEdit", "canSeeCheckpointData" ], "type": "object" }, "SkillCollapse": { "additionalProperties": false, "properties": { "defaultCollapsed": { "type": "boolean" }, "label": { "type": "string" }, "target": { "type": "string" } }, "type": "object" }, "SkillEvent": { "additionalProperties": false, "properties": { "collapse": { "$ref": "#/components/schemas/SkillCollapse" }, "eventType": { "type": "string" }, "id": { "type": "string" }, "native": { "additionalProperties": { "type": "string" }, "type": "object" }, "skill": { "$ref": "#/components/schemas/SkillEventSkill" }, "source": { "$ref": "#/components/schemas/TranscriptSkillSource" }, "timestamp": { "type": "string" }, "transcriptAnchor": { "$ref": "#/components/schemas/SkillTranscriptAnchor" }, "turnId": { "type": "string" } }, "required": [ "eventType", "skill" ], "type": "object" }, "SkillEventSkill": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "SkillTranscriptAnchor": { "additionalProperties": false, "properties": { "end": { "format": "int64", "type": "integer" }, "entryIds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "start": { "format": "int64", "type": "integer" }, "toolUseId": { "type": "string" }, "unit": { "type": "string" } }, "type": "object" }, "SnapshotCommentJSON": { "additionalProperties": false, "properties": { "outgoing_links": { "items": { "$ref": "#/components/schemas/ReviewCommentLinkJSON" }, "type": [ "array", "null" ] }, "suggested_changes": { "items": { "$ref": "#/components/schemas/SuggestedChangeJSON" }, "type": [ "array", "null" ] } }, "required": [ "suggested_changes", "outgoing_links" ], "type": "object" }, "StartReviewResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/StartReviewResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "base_sha": { "type": [ "string", "null" ] }, "code_version_id": { "type": "string" }, "diff_url": { "type": "string" }, "event_stream_url": { "type": "string" }, "files_url": { "type": "string" }, "head_sha": { "type": [ "string", "null" ] }, "limits": { "$ref": "#/components/schemas/ReviewLimitsJSON" }, "repo_id": { "type": "string" }, "review_id": { "type": "string" }, "trail_id": { "type": "string" } }, "required": [ "review_id", "trail_id", "repo_id", "code_version_id", "base_sha", "head_sha", "event_stream_url", "diff_url", "files_url", "limits" ], "type": "object" }, "StateCounts": { "additionalProperties": false, "properties": { "checkpoints": { "format": "int64", "type": "integer" }, "commits": { "format": "int64", "type": "integer" } }, "required": [ "commits", "checkpoints" ], "type": "object" }, "StreakStruct": { "additionalProperties": false, "properties": { "current_days": { "format": "int64", "type": "integer" }, "longest_days": { "format": "int64", "type": "integer" } }, "required": [ "current_days", "longest_days" ], "type": "object" }, "SubagentHandback": { "additionalProperties": false, "properties": { "source": { "description": "Open set: where the report was read. claude_handback is the child's last SubagentHandback tool call; codex_final_answer is the newest FINAL_ANSWER agent_message the child sent, read from the parent rollout. Unknown future values must be tolerated.", "type": "string", "x-open-enum": [ "claude_handback", "codex_final_answer" ] }, "text": { "description": "the report, markdown", "type": "string" }, "timestamp": { "description": "when the parent received the report, RFC 3339; null when the source records none", "type": [ "string", "null" ] }, "truncated": { "description": "true only when text is a shortened preview of the source report; false for Codex reports, which are returned whole. Capture and resolution uncertainty is reported by handbackIncomplete", "type": "boolean" } }, "required": [ "text", "source", "truncated", "timestamp" ], "type": "object" }, "SubagentHandbackMessage": { "additionalProperties": false, "properties": { "kind": { "description": "Open set: final_answer is a result; message is interim progress or a question. Unknown future values must be tolerated.", "type": "string", "x-open-enum": [ "final_answer", "message" ] }, "text": { "description": "the message, markdown", "type": "string" }, "timestamp": { "description": "when the parent received it, RFC 3339", "type": "string" } }, "required": [ "kind", "text", "timestamp" ], "type": "object" }, "SubagentSummaryItem": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "checkpointCount": { "description": "distinct checkpoints that captured this subagent", "format": "int64", "type": "integer" }, "lastActivityAt": { "description": "newest known checkpoint capture time; when no capture time is known yet, the task's own completed_at, else started_at", "type": "string" }, "nativeAgentId": { "description": "the agent's own id for the subagent (Claude Code agent_id); null when the CLI recorded none", "type": [ "string", "null" ] }, "parentToolUseId": { "description": "tool_use id of the sibling subagent's Task call that launched this one; null when the session itself launched it or the launching call was not captured", "type": [ "string", "null" ] }, "startedAt": { "description": "earliest started_at recorded across captures, RFC 3339", "type": "string" }, "subagentId": { "type": "string" }, "taskDescription": { "description": "the Task call's description as recorded by the newest capture; for Codex, which records none, the spawn_agent task_name", "type": "string" }, "toolUseId": { "description": "id of the parent tool call the subagent was launched from: the Task tool_use id (the same value as subagentId) for Claude Code, the spawn_agent call_id for Codex; for Codex, subagentId when the launching call could not be found in the parent transcript", "type": [ "string", "null" ] } }, "required": [ "subagentId", "toolUseId", "nativeAgentId", "agent", "taskDescription", "startedAt", "lastActivityAt", "checkpointCount", "parentToolUseId" ], "type": "object" }, "SuggestedChangeJSON": { "additionalProperties": false, "properties": { "change_type": { "type": "string" }, "code_version_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "expected_end_line": { "format": "int64", "type": [ "integer", "null" ] }, "expected_file_hash": { "type": [ "string", "null" ] }, "expected_file_path": { "type": [ "string", "null" ] }, "expected_lines": { "type": [ "string", "null" ] }, "expected_start_line": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "type": "string" }, "instruction": { "type": [ "string", "null" ] }, "patch": { "type": [ "string", "null" ] }, "review_comment_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "review_comment_id", "code_version_id", "change_type", "patch", "instruction", "expected_file_path", "expected_file_hash", "expected_start_line", "expected_end_line", "expected_lines", "created_by", "created_at", "updated_at" ], "type": "object" }, "SummaryBody": { "additionalProperties": false, "properties": { "active_days": { "format": "int64", "type": "integer" }, "additions": { "format": "int64", "type": "integer" }, "cache_creation_tokens": { "format": "int64", "type": "integer" }, "cache_read_tokens": { "format": "int64", "type": "integer" }, "checkpoints": { "format": "int64", "type": "integer" }, "commits": { "format": "int64", "type": "integer" }, "contributors": { "format": "int64", "type": "integer" }, "deletions": { "format": "int64", "type": "integer" }, "files_changed": { "format": "int64", "type": "integer" }, "first_activity": { "format": "date-time", "type": "string" }, "input_tokens": { "format": "int64", "type": "integer" }, "last_activity": { "format": "date-time", "type": "string" }, "output_tokens": { "format": "int64", "type": "integer" }, "sessions": { "format": "int64", "type": "integer" }, "steps": { "format": "int64", "type": "integer" } }, "required": [ "commits", "checkpoints", "contributors", "additions", "deletions", "files_changed", "input_tokens", "output_tokens", "cache_creation_tokens", "cache_read_tokens", "steps", "sessions", "active_days" ], "type": "object" }, "SummarySection": { "additionalProperties": false, "properties": { "narrative": { "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "narrative" ], "type": "object" }, "SummaryStruct": { "additionalProperties": false, "properties": { "active_days": { "format": "int64", "type": "integer" }, "checkpoints": { "format": "int64", "type": "integer" }, "repo_count": { "format": "int64", "type": "integer" }, "tokens": { "format": "int64", "type": "integer" } }, "required": [ "checkpoints", "tokens", "active_days", "repo_count" ], "type": "object" }, "TimelineEvent": { "additionalProperties": false, "type": "object" }, "ToolCall": { "additionalProperties": false, "properties": { "categories": { "items": { "description": "Open timeline filter category. Clients must tolerate values added in the future.", "type": "string", "x-open-enum": [ "fileEdits", "bash", "read", "skills", "entire", "other" ] }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "input": { "additionalProperties": {}, "type": "object" }, "metadata": { "$ref": "#/components/schemas/ToolCallMetadata" }, "name": { "type": "string" }, "operations": { "items": { "$ref": "#/components/schemas/ToolCall" }, "type": [ "array", "null" ] }, "result": { "$ref": "#/components/schemas/ToolCallResult" }, "skillInvocation": { "$ref": "#/components/schemas/TranscriptSkillInvocation" }, "timestamp": { "type": "string" } }, "required": [ "timestamp", "id", "name", "input" ], "type": "object" }, "ToolCallMetadata": { "additionalProperties": false, "properties": { "mcpServer": { "type": "string" } }, "type": "object" }, "ToolCallResult": { "additionalProperties": false, "properties": { "answers": { "additionalProperties": { "type": "string" }, "type": "object" }, "error": { "type": "string" }, "file": { "$ref": "#/components/schemas/ToolResultFile" }, "matchCount": { "format": "int64", "type": "integer" }, "output": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type" ], "type": "object" }, "ToolResultFile": { "additionalProperties": false, "properties": { "filePath": { "type": "string" }, "numLines": { "format": "int64", "type": "integer" } }, "required": [ "filePath" ], "type": "object" }, "TrailActionAvailability": { "additionalProperties": false, "properties": { "reason": { "type": [ "string", "null" ] }, "state": { "enum": [ "enabled", "blocked", "unavailable" ], "type": "string" } }, "required": [ "state", "reason" ], "type": "object" }, "TrailActions": { "additionalProperties": false, "properties": { "approve": { "$ref": "#/components/schemas/TrailActionAvailability" }, "create_ci_pr": { "$ref": "#/components/schemas/TrailActionAvailability" }, "delete_branch": { "$ref": "#/components/schemas/TrailActionAvailability" }, "merge": { "$ref": "#/components/schemas/TrailActionAvailability" }, "merge_with_bypass": { "$ref": "#/components/schemas/TrailActionAvailability" }, "restore_branch": { "$ref": "#/components/schemas/TrailActionAvailability" }, "update_branch": { "$ref": "#/components/schemas/TrailActionAvailability" } }, "required": [ "approve", "create_ci_pr", "merge", "merge_with_bypass", "update_branch", "restore_branch", "delete_branch" ], "type": "object" }, "TrailActivity": { "additionalProperties": false, "properties": { "active": { "format": "int64", "type": "integer" }, "created": { "format": "int64", "type": "integer" }, "daily": { "items": { "$ref": "#/components/schemas/TrailActivityDay" }, "type": [ "array", "null" ] }, "merged": { "format": "int64", "type": "integer" } }, "required": [ "active", "created", "merged", "daily" ], "type": "object" }, "TrailActivityDay": { "additionalProperties": false, "properties": { "active": { "format": "int64", "type": "integer" }, "created": { "format": "int64", "type": "integer" }, "date": { "type": "string" }, "merged": { "format": "int64", "type": "integer" } }, "required": [ "date", "active", "created", "merged" ], "type": "object" }, "TrailAgentJSON": { "additionalProperties": false, "properties": { "agent": { "$ref": "#/components/schemas/TrailAgentRefJSON" }, "history": { "description": "Finished readings of the current value type, newest first, at most six.", "items": { "$ref": "#/components/schemas/TrailAgentReadingJSON" }, "type": [ "array", "null" ] }, "latest_run": { "allOf": [ { "description": "The agent's latest run on the Change, finished or not; null while it waits for its first." }, { "$ref": "#/components/schemas/TrailAgentRunJSON" } ] }, "reading": { "allOf": [ { "description": "The latest finished reading of the signal's current value type; null until one exists." }, { "$ref": "#/components/schemas/TrailAgentReadingJSON" } ] }, "signal": { "allOf": [ { "description": "The signal its latest run reports, or a waiting agent's own: its review distilled into one reading." }, { "$ref": "#/components/schemas/AgentSignal" } ] }, "trend_delta": { "description": "The reading minus the one before it (percent points, or steps of small/medium/large, false/true); null without two.", "format": "int64", "type": [ "integer", "null" ] }, "waiting_for": { "description": "Set while the agent has no run on the Change: ready, it runs once the Change is ready for review; not_ready, it runs only before the Change is ready for review, so not on this one while it stays ready; push, it runs on the next push (or run it now).", "enum": [ "ready", "not_ready", "push" ], "type": [ "string", "null" ] } }, "required": [ "agent", "signal", "reading", "trend_delta", "latest_run", "waiting_for", "history" ], "type": "object" }, "TrailAgentReadingJSON": { "additionalProperties": false, "properties": { "boolean_value": { "type": [ "boolean", "null" ] }, "head_sha": { "description": "The head it reviewed.", "type": [ "string", "null" ] }, "percent_value": { "format": "int64", "type": [ "integer", "null" ] }, "rationale": { "type": [ "string", "null" ] }, "run_id": { "description": "The run that produced it.", "type": "string" }, "size_value": { "enum": [ "small", "medium", "large" ], "type": [ "string", "null" ] }, "summary": { "description": "The review as a whole; null for a result from before summaries.", "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": "string" }, "verdicts": { "allOf": [ { "description": "The run's verdicts on the agent's earlier open findings." }, { "$ref": "#/components/schemas/TrailAgentVerdictsJSON" } ] } }, "required": [ "percent_value", "size_value", "boolean_value", "rationale", "summary", "verdicts", "run_id", "head_sha", "updated_at" ], "type": "object" }, "TrailAgentRefJSON": { "additionalProperties": false, "properties": { "id": { "description": "Agent id (GET .../agents/{id}); stable across every edit of the agent.", "type": "string" }, "name": { "description": "The agent's current name.", "type": "string" }, "preset": { "allOf": [ { "description": "The Entire preset the agent runs now, or null for a custom agent." }, { "$ref": "#/components/schemas/AgentPresetRef" } ] } }, "required": [ "id", "name", "preset" ], "type": "object" }, "TrailAgentRunJSON": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "error": { "allOf": [ { "description": "Why the run failed or timed out; null otherwise." }, { "$ref": "#/components/schemas/RunError" } ] }, "head_sha": { "type": [ "string", "null" ] }, "id": { "description": "The run (GET .../runs/{id}).", "type": "string" }, "status": { "enum": [ "queued", "running", "succeeded", "failed", "timed_out", "canceled" ], "type": "string" } }, "required": [ "id", "status", "head_sha", "created_at", "error" ], "type": "object" }, "TrailAgentVerdictsJSON": { "additionalProperties": false, "properties": { "decided_by_person": { "description": "Verdicts a person's decision overrode (already_closed, reopened_by_person); not counted above.", "format": "int64", "type": "integer" }, "fixed": { "format": "int64", "type": "integer" }, "no_longer_applies": { "format": "int64", "type": "integer" }, "still_present": { "format": "int64", "type": "integer" } }, "required": [ "fixed", "still_present", "no_longer_applies", "decided_by_person" ], "type": "object" }, "TrailApprovalSubmitBody": { "additionalProperties": false, "properties": { "body": { "type": "string" }, "event": { "type": "string" } }, "required": [ "event" ], "type": "object" }, "TrailApprovalSubmitRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailApprovalSubmitRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": { "description": "Required and non-blank for request_changes.", "type": "string" }, "event": { "enum": [ "approve", "request_changes" ], "type": "string" } }, "required": [ "event" ], "type": "object" }, "TrailApprovalSubmitResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailApprovalSubmitResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "approval": { "$ref": "#/components/schemas/TrailApprovalWire" }, "gates": { "$ref": "#/components/schemas/TrailGatesResponse" }, "ok": { "type": "boolean" } }, "required": [ "ok", "approval", "gates" ], "type": "object" }, "TrailApprovalWire": { "additionalProperties": false, "properties": { "author": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "commit_sha": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "event": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "author", "event", "body", "commit_sha", "created_at" ], "type": "object" }, "TrailApprovalsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailApprovalsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "approvals": { "items": { "$ref": "#/components/schemas/TrailApprovalWire" }, "type": [ "array", "null" ] } }, "required": [ "approvals" ], "type": "object" }, "TrailAssigneeIdentity": { "additionalProperties": false, "properties": { "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "login": { "type": [ "string", "null" ] } }, "required": [ "login", "identity" ], "type": "object" }, "TrailAuthor": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "login": { "type": [ "string", "null" ] } }, "required": [ "id", "login", "identity" ], "type": "object" }, "TrailBodyDocumentJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailBodyDocumentJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "content_json": {}, "document_key": { "type": "string" }, "etag": { "type": "string" }, "id": { "type": "string" }, "schema_version": { "format": "int64", "type": "integer" }, "text_snapshot": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "document_key", "schema_version", "content_json", "text_snapshot", "updated_at", "etag" ], "type": "object" }, "TrailCIPrResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailCIPrResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "prNumber": { "description": "GitHub pull request number now backing the Trail", "format": "int64", "type": "integer" } }, "required": [ "prNumber" ], "type": "object" }, "TrailChangeCreateInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailChangeCreateInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "assignees": {}, "base": {}, "branchAction": {}, "branchName": {}, "priority": {}, "readyForReview": {}, "repositoryId": { "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$", "type": "string" }, "status": {}, "title": {}, "type": {} }, "required": [ "repositoryId" ], "type": "object" }, "TrailChangeCreateOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailChangeCreateOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "id": { "type": "string" }, "repositoryId": { "type": "string" }, "trailId": { "type": "string" } }, "required": [ "id", "trailId", "repositoryId" ], "type": "object" }, "TrailCheckRunJSON": { "additionalProperties": false, "properties": { "app_name": { "type": [ "string", "null" ] }, "completed_at": { "format": "date-time", "type": [ "string", "null" ] }, "conclusion": { "type": [ "string", "null" ] }, "details_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "source": { "description": "Slug of the CI plugin that reported this run. Absent for a run read from the forge.", "type": "string" }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": "string" }, "steps": { "items": { "$ref": "#/components/schemas/CheckRunStep" }, "type": [ "array", "null" ] } }, "required": [ "name", "status", "conclusion", "details_url", "started_at", "completed_at", "app_name" ], "type": "object" }, "TrailChecksJSON": { "additionalProperties": false, "properties": { "availability": { "description": "available means a complete read, including an empty list; unavailable means missing or failed evidence; not_applicable means no applicable CI evidence.", "enum": [ "available", "unavailable", "not_applicable" ], "type": "string" }, "runs": { "items": { "$ref": "#/components/schemas/TrailCheckRunJSON" }, "type": [ "array", "null" ] } }, "required": [ "availability", "runs" ], "type": "object" }, "TrailCommandBody": { "additionalProperties": false, "properties": { "baseSha": { "description": "Frozen compare-snapshot base tip SHA (hex)", "type": "string" }, "ghPrId": { "description": "Known forge change-proposal id", "format": "int64", "type": "integer" }, "hasCodeChanges": { "description": "Externally-computed building-state flag (applied only while the trail is open)", "type": "boolean" }, "headSha": { "description": "Frozen compare-snapshot head SHA (hex)", "type": "string" }, "mergeBaseSha": { "description": "Frozen compare-snapshot merge-base SHA (hex)", "type": "string" }, "mergedAt": { "description": "RFC3339 instant the change proposal merged; also transitions the trail to status=merged to keep merged_at and status consistent", "type": "string" } }, "type": "object" }, "TrailCreateRequestBody": { "additionalProperties": false, "properties": { "assignees": {}, "base": {}, "branch_action": {}, "branch_name": {}, "priority": {}, "ready_for_review": {}, "status": {}, "title": {}, "type": {} }, "type": "object" }, "TrailCreateRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailCreateRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "assignees": { "items": { "oneOf": [ { "description": "An actor reference: ulid:\u003caccount id\u003e or @username. A bare string is a GitHub login (legacy).", "type": "string" }, { "properties": { "actor_account_id": { "description": "An Entire account ULID.", "type": "string" } }, "required": [ "actor_account_id" ], "type": "object" } ] }, "type": "array" }, "base": { "minLength": 1, "type": "string" }, "branch_action": { "enum": [ "create", "link" ], "type": "string" }, "branch_name": { "minLength": 1, "type": "string" }, "priority": { "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "ready_for_review": { "type": "boolean" }, "status": { "enum": [ "open", "closed" ], "type": "string" }, "title": { "minLength": 1, "type": "string" }, "type": { "enum": [ "bug", "feature", "task" ], "type": "string" } }, "required": [ "title", "branch_name" ], "type": "object" }, "TrailCreateResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailCreateResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "has_new_branch": { "type": "boolean" }, "trail": { "$ref": "#/components/schemas/TrailWriteJSON" } }, "required": [ "trail", "has_new_branch" ], "type": "object" }, "TrailDeployment": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "type": "string" }, "conclusion": { "enum": [ "success", "failure", "cancelled", "skipped" ], "type": "string" }, "deadline_at": { "format": "date-time", "type": "string" }, "environment": { "description": "Defaults to preview; the only documented environment in v0.", "maxLength": 64, "type": "string" }, "environment_url": { "maxLength": 2048, "type": "string" }, "external_updated_at": { "format": "date-time", "type": "string" }, "group": { "$ref": "#/components/schemas/DeploymentGroup" }, "id": { "type": "string" }, "key": { "description": "Stable resource id, unique per plugin and commit. At most 255 characters.", "maxLength": 255, "type": "string" }, "logs_url": { "maxLength": 2048, "type": "string" }, "name": { "maxLength": 255, "type": "string" }, "plugin": { "type": "string" }, "stale": { "description": "queued or in_progress past deadline_at; the reported status is unchanged.", "type": "boolean" }, "started_at": { "format": "date-time", "type": "string" }, "status": { "description": "inactive: the resource no longer exists, such as a torn-down preview; do not offer its links.", "enum": [ "queued", "in_progress", "completed", "inactive" ], "type": "string" }, "type": { "maxLength": 64, "type": "string" } }, "required": [ "stale", "id", "plugin", "key", "name", "status", "external_updated_at" ], "type": "object" }, "TrailDeployments": { "additionalProperties": false, "properties": { "availability": { "description": "available: read succeeded (possibly empty). unavailable: the read failed; not zero deployments. not_applicable: no head SHA.", "enum": [ "available", "unavailable", "not_applicable" ], "type": "string" }, "items": { "description": "Latest resource per plugin and key on this SHA; always an array.", "items": { "$ref": "#/components/schemas/TrailDeployment" }, "type": [ "array", "null" ] }, "ready": { "description": "Resources completed with conclusion success.", "format": "int64", "type": "integer" }, "total": { "description": "Resources that can become ready: skipped and inactive ones are excluded, so ready can reach total.", "format": "int64", "type": "integer" } }, "required": [ "items", "availability", "ready", "total" ], "type": "object" }, "TrailDetailResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDetailResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "actions": { "allOf": [ { "description": "Availability by operation for this caller and Trail snapshot. The server revalidates every submitted command." }, { "$ref": "#/components/schemas/TrailActions" } ] }, "agents": { "description": "Saved agents with a run on this Change, apart from the repository runners' monitors: each one's latest run, its signal's readings and who it is.", "items": { "$ref": "#/components/schemas/TrailAgentJSON" }, "type": [ "array", "null" ] }, "assignee_identities": { "items": { "$ref": "#/components/schemas/TrailAssigneeIdentity" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailAuthor" }, "base": { "type": "string" }, "base_sha": { "type": [ "string", "null" ] }, "body_document": { "$ref": "#/components/schemas/TrailBodyDocumentJSON" }, "branch": { "type": [ "string", "null" ] }, "branch_state": { "description": "Observed availability of the associated branch. Unknown is not a deletion; original_branch is a historical name, not proof of a live branch.", "enum": [ "present", "deleted", "unlinked", "unknown" ], "type": "string" }, "code_changes": { "description": "Current code evidence: present means commits ahead of base, none means a confirmed zero or an indexed base tip equal to the displayed head when comparison is unavailable, unknown means no usable evidence for a Change that tracks a branch. not_applicable means no live comparison exists (merged, closed or unlinked); terminal history uses frozen snapshot refs.", "enum": [ "present", "none", "unknown", "not_applicable" ], "type": "string" }, "comment_count": { "format": "int64", "type": "integer" }, "config_source": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "deployments": { "allOf": [ { "description": "Deployments at the current or frozen head; display-only, independent of checks and merge gates." }, { "$ref": "#/components/schemas/TrailDeployments" } ] }, "gh_pr_id": { "format": "int64", "type": "integer" }, "has_code_changes": { "type": "boolean" }, "head_sha": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "last_activity_at": { "description": "Latest meaningful activity on the Change; excludes background bookkeeping and falls back to created_at until activity is recorded.", "format": "date-time", "type": "string" }, "lifecycle_sync": { "description": "Pending means linked PR metadata reports a terminal transition not yet applied to this Change, or the linked PR's head branch was deleted. Settled means no such observed transition, not a guarantee that all webhooks have arrived.", "enum": [ "settled", "pending" ], "type": "string" }, "merge_base_sha": { "type": [ "string", "null" ] }, "mergeability": { "$ref": "#/components/schemas/TrailMergeabilityResponse" }, "merged_at": { "format": "date-time", "type": [ "string", "null" ] }, "monitors": { "items": { "$ref": "#/components/schemas/TrailMonitorItemJSON" }, "type": [ "array", "null" ] }, "number": { "format": "int64", "type": "integer" }, "original_branch": { "type": [ "string", "null" ] }, "parent": { "allOf": [ { "description": "Discoverable project parent on list/detail reads; absence does not prove the work is parentless" }, { "$ref": "#/components/schemas/TrailParentReference" } ] }, "phase": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "ready_for_review": { "type": "boolean" }, "reviewers": { "items": { "$ref": "#/components/schemas/TrailReviewer" }, "type": [ "array", "null" ] }, "runners": { "items": { "$ref": "#/components/schemas/TrailRunnerItemJSON" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "unresolved_count": { "format": "int64", "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "description": "Web app page for this code work; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "body_document", "monitors", "agents", "runners", "actions", "mergeability", "config_source", "merge_base_sha", "base_sha", "head_sha", "id", "number", "title", "status", "branch", "original_branch", "base", "type", "priority", "author", "assignees", "assignee_identities", "reviewers", "ready_for_review", "has_code_changes", "comment_count", "unresolved_count", "created_at", "updated_at", "merged_at", "last_activity_at", "phase", "branch_state", "code_changes", "lifecycle_sync" ], "type": "object" }, "TrailDiscussionCreateBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionCreateBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": {}, "title": {} }, "type": "object" }, "TrailDiscussionCreateRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionCreateRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": { "maxLength": 65536, "minLength": 1, "type": "string" }, "title": { "maxLength": 512, "minLength": 1, "type": "string" } }, "required": [ "body" ], "type": "object" }, "TrailDiscussionCreateResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionCreateResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "discussion": { "$ref": "#/components/schemas/TrailDiscussionSummaryJSON" }, "message": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" } }, "required": [ "discussion", "message" ], "type": "object" }, "TrailDiscussionDetailResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionDetailResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "discussion": { "$ref": "#/components/schemas/TrailDiscussionSummaryJSON" }, "event_cursor": { "type": "string" }, "messages": { "items": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" }, "type": [ "array", "null" ] } }, "required": [ "discussion", "messages", "event_cursor" ], "type": "object" }, "TrailDiscussionEventJSON": { "additionalProperties": false, "properties": { "actor_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "discussion_id": { "type": [ "string", "null" ] }, "event_type": { "type": "string" }, "id": { "type": "string" }, "payload": {}, "target_id": { "type": "string" }, "trail_id": { "type": "string" } }, "required": [ "id", "trail_id", "discussion_id", "actor_id", "event_type", "target_id", "payload", "created_at" ], "type": "object" }, "TrailDiscussionEventsResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionEventsResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/TrailDiscussionEventJSON" }, "type": [ "array", "null" ] } }, "required": [ "events" ], "type": "object" }, "TrailDiscussionMessageBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionMessageBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": {} }, "type": "object" }, "TrailDiscussionMessageCreateRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionMessageCreateRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": { "maxLength": 65536, "minLength": 1, "type": "string" } }, "required": [ "body" ], "type": "object" }, "TrailDiscussionMessageJSON": { "additionalProperties": false, "properties": { "author": { "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "etag": { "type": "string" }, "id": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "replies": { "items": { "$ref": "#/components/schemas/TrailDiscussionMessageReplyJSON" }, "type": [ "array", "null" ] } }, "required": [ "id", "author", "identity", "created_at", "body", "replies" ], "type": "object" }, "TrailDiscussionMessageReplyJSON": { "additionalProperties": false, "properties": { "author": { "type": "string" }, "body": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" } }, "required": [ "id", "author", "identity", "created_at", "body" ], "type": "object" }, "TrailDiscussionMessageResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionMessageResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "message": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" } }, "required": [ "message" ], "type": "object" }, "TrailDiscussionMessageUpdateRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionMessageUpdateRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "body": { "maxLength": 65536, "minLength": 1, "type": "string" } }, "type": "object" }, "TrailDiscussionParticipantJSON": { "additionalProperties": false, "properties": { "actor_account_id": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "login": { "type": "string" } }, "required": [ "login", "identity" ], "type": "object" }, "TrailDiscussionSummaryJSON": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": [ "string", "null" ] }, "created_by_identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "etag": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "last_message_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_message_author": { "type": [ "string", "null" ] }, "message_count": { "format": "int64", "type": "integer" }, "messages": { "description": "Only on the list route with include_messages=true", "items": { "$ref": "#/components/schemas/TrailDiscussionMessageJSON" }, "type": "array" }, "participants": { "items": { "$ref": "#/components/schemas/TrailDiscussionParticipantJSON" }, "type": [ "array", "null" ] }, "resolved": { "type": "boolean" }, "resolved_at": { "format": "date-time", "type": [ "string", "null" ] }, "resolved_by": { "type": [ "string", "null" ] }, "resolved_by_identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "review_comment": { "$ref": "#/components/schemas/ReviewCommentJSON" }, "review_comment_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "trail_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "trail_id", "title", "kind", "resolved", "resolved_by", "resolved_by_identity", "resolved_at", "created_by", "created_by_identity", "created_at", "updated_at", "last_message_at", "last_message_author", "message_count", "participants", "review_comment_id", "review_comment" ], "type": "object" }, "TrailDiscussionUpdateBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionUpdateBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "resolved": {}, "title": {} }, "type": "object" }, "TrailDiscussionUpdateRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionUpdateRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "resolved": { "type": "boolean" }, "title": { "maxLength": 512, "minLength": 1, "type": "string" } }, "type": "object" }, "TrailDiscussionUpdateResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionUpdateResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "discussion": { "$ref": "#/components/schemas/TrailDiscussionSummaryJSON" } }, "required": [ "discussion" ], "type": "object" }, "TrailDiscussionsListResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailDiscussionsListResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "event_cursor": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/TrailDiscussionSummaryJSON" }, "type": [ "array", "null" ] }, "next_cursor": { "type": "string" } }, "required": [ "items", "event_cursor" ], "type": "object" }, "TrailGateConfigResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailGateConfigResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "gates": { "items": { "$ref": "#/components/schemas/GateDefinition" }, "type": [ "array", "null" ] }, "gatesEnabled": { "type": "boolean" } }, "required": [ "gates", "gatesEnabled" ], "type": "object" }, "TrailGatesResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailGatesResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "blocking_failures": { "items": { "$ref": "#/components/schemas/GateResult" }, "type": [ "array", "null" ] }, "evaluated_at": { "format": "date-time", "type": [ "string", "null" ] }, "gates": { "items": { "$ref": "#/components/schemas/GateResult" }, "type": [ "array", "null" ] }, "gates_enabled": { "type": "boolean" }, "head_sha": { "type": [ "string", "null" ] }, "mergeable": { "description": "Whether the evaluated gates allow merging. Does not include merge conflicts or guarantee fresh CI evidence. Use /mergeability for current merge readiness.", "type": "boolean" } }, "required": [ "gates_enabled", "head_sha", "gates", "blocking_failures", "mergeable", "evaluated_at" ], "type": "object" }, "TrailListItem": { "additionalProperties": false, "properties": { "assignee_identities": { "items": { "$ref": "#/components/schemas/TrailAssigneeIdentity" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailAuthor" }, "base": { "type": "string" }, "branch": { "type": [ "string", "null" ] }, "comment_count": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "has_code_changes": { "type": "boolean" }, "id": { "type": "string" }, "last_activity_at": { "description": "Latest meaningful activity on the Change; excludes background bookkeeping and falls back to created_at until activity is recorded.", "format": "date-time", "type": "string" }, "merged_at": { "format": "date-time", "type": [ "string", "null" ] }, "number": { "format": "int64", "type": "integer" }, "original_branch": { "type": [ "string", "null" ] }, "parent": { "allOf": [ { "description": "Discoverable project parent on list/detail reads; absence does not prove the work is parentless" }, { "$ref": "#/components/schemas/TrailParentReference" } ] }, "phase": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "ready_for_review": { "type": "boolean" }, "reviewers": { "items": { "$ref": "#/components/schemas/TrailReviewer" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "unresolved_count": { "format": "int64", "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "description": "Web app page for this code work; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "id", "number", "title", "status", "branch", "original_branch", "base", "type", "priority", "author", "assignees", "assignee_identities", "reviewers", "ready_for_review", "has_code_changes", "comment_count", "unresolved_count", "created_at", "updated_at", "merged_at", "last_activity_at", "phase" ], "type": "object" }, "TrailMergeSubmitBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailMergeSubmitBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "bypass": { "type": "boolean" }, "deleteBranch": { "description": "Delete the native Trail's working branch after the merge, first moving the open and draft Trails based on it to the merged Trail's base, as the merger. Omitted uses the repository's deleteBranchOnMerge setting. Ignored for GitHub-backed Trails.", "type": "boolean" }, "expectedHeadSha": { "type": "string" } }, "type": "object" }, "TrailMergeSubmitResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailMergeSubmitResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branchDeleted": { "description": "The Trail's working branch no longer exists after the merge. Always false for a GitHub-backed Trail, whose branch GitHub manages.", "type": "boolean" }, "branchKeptReason": { "description": "Why the native Trail's working branch was kept. Set only when branchDeleted is false; omitted for a GitHub-backed Trail. not_requested: the request sent deleteBranch false. disabled: deleteBranch was omitted and the repository's deleteBranchOnMerge setting is off. base: the branch is the Trail's base. stacked: an open or draft Trail based on the branch could not be moved to the merged Trail's base. claimed: another Trail took the branch name after the merge. moved: the branch moved past the merged head. protected: branch protection refused the delete. default_branch: the branch is the repository's default branch. failed: the delete, or moving the Trails based on the branch, could not run or did not succeed.", "enum": [ "not_requested", "disabled", "base", "stacked", "claimed", "moved", "protected", "default_branch", "failed" ], "type": "string" }, "mergeCommitSha": { "description": "Merge commit SHA; empty when the merge fast-forwarded or was already up to date", "type": "string" }, "ok": { "type": "boolean" } }, "required": [ "ok", "mergeCommitSha", "branchDeleted" ], "type": "object" }, "TrailMergeabilityResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailMergeabilityResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "behind_by": { "format": "int64", "type": "integer" }, "bypass_policy": { "description": "Effective bypass policy for this response. When readiness is unavailable, nobody is a fail-closed fallback, not the saved repository setting; merge actions remain unavailable.", "type": "string" }, "checks": { "allOf": [ { "description": "Third-party CI runs for headSha from the same read that evaluated the checks gate; Entire's own gate rollup is excluded. On an open native trail whose checks gate is pending, each required name with no report is also listed, with status queued and no started_at, whatever checks.availability says. Reported runs are meaningful only when checks.availability is available." }, { "$ref": "#/components/schemas/TrailChecksJSON" } ] }, "comparison_status": { "type": "string" }, "conflict_status": { "description": "Provider conflict verdict for headSha; conflicting blocks mergeable independently of gates and CI evidence.", "enum": [ "clean", "conflicting", "unknown" ], "type": "string" }, "delete_branch_on_merge": { "description": "Default for the merge request's deleteBranch option, i.e. the repository's delete-branch-on-merge setting; false means the setting is off. Null for a GitHub-backed repository, where entire-api never deletes the branch, and when readiness is unavailable.", "type": [ "boolean", "null" ] }, "forge_merge_block": { "allOf": [ { "description": "Set when the forge's own branch rules (GitHub branch protection or rulesets) refuse the merge at headSha, independent of Entire's gates. Read under the GitHub App's credential, so it does not reflect a viewer's ability to bypass. Null when not blocked or unknown, and when GitHub waits only on Entire's own gates check run, which the gates already report." }, { "$ref": "#/components/schemas/ForgeMergeBlockJSON" } ] }, "gates": { "items": { "$ref": "#/components/schemas/GateResult" }, "type": [ "array", "null" ] }, "head_sha": { "type": [ "string", "null" ] }, "mergeable": { "type": "boolean" } }, "required": [ "delete_branch_on_merge", "bypass_policy", "mergeable", "behind_by", "comparison_status", "conflict_status", "head_sha", "gates", "checks", "forge_merge_block" ], "type": "object" }, "TrailMonitorFailedAttemptJSON": { "additionalProperties": false, "properties": { "failed_at": { "format": "date-time", "type": "string" }, "head_sha": { "type": [ "string", "null" ] }, "run_id": { "type": "string" } }, "required": [ "run_id", "head_sha", "failed_at" ], "type": "object" }, "TrailMonitorHistoryItemJSON": { "additionalProperties": false, "properties": { "boolean_value": { "type": [ "boolean", "null" ] }, "evaluating": { "type": "boolean" }, "head_sha": { "type": [ "string", "null" ] }, "percent_value": { "format": "int64", "type": [ "integer", "null" ] }, "rationale": { "type": [ "string", "null" ] }, "run_id": { "type": "string" }, "size_value": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "percent_value", "size_value", "boolean_value", "rationale", "run_id", "head_sha", "updated_at" ], "type": "object" }, "TrailMonitorItemJSON": { "additionalProperties": false, "properties": { "boolean_value": { "type": [ "boolean", "null" ] }, "evaluated_at_sha": { "type": [ "string", "null" ] }, "evaluating": { "type": "boolean" }, "head_sha": { "type": [ "string", "null" ] }, "history": { "items": { "$ref": "#/components/schemas/TrailMonitorHistoryItemJSON" }, "type": [ "array", "null" ] }, "key": { "type": "string" }, "label": { "type": "string" }, "last_failed_attempt": { "$ref": "#/components/schemas/TrailMonitorFailedAttemptJSON" }, "outcome": { "type": [ "string", "null" ] }, "percent_value": { "format": "int64", "type": [ "integer", "null" ] }, "polarity": { "type": [ "string", "null" ] }, "rationale": { "type": [ "string", "null" ] }, "run_id": { "type": "string" }, "size_value": { "type": [ "string", "null" ] }, "stale_reason": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "trend_delta": { "format": "int64", "type": [ "integer", "null" ] }, "updated_at": { "format": "date-time", "type": "string" }, "value_type": { "type": "string" } }, "required": [ "key", "label", "value_type", "percent_value", "size_value", "boolean_value", "rationale", "polarity", "trend_delta", "evaluating", "last_failed_attempt", "history", "run_id", "head_sha", "updated_at", "state", "outcome", "stale_reason", "evaluated_at_sha" ], "type": "object" }, "TrailMonitorsResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailMonitorsResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "configSource": { "type": "string" }, "monitors": { "items": { "$ref": "#/components/schemas/TrailMonitorItemJSON" }, "type": [ "array", "null" ] } }, "required": [ "monitors", "configSource" ], "type": "object" }, "TrailParentReference": { "additionalProperties": false, "properties": { "host": { "enum": [ "gh", "et" ], "type": "string" }, "id": { "type": "string" }, "jurisdiction": { "description": "Project jurisdiction from Core; empty when unresolved", "type": "string" }, "number": { "description": "Project-local Trail number, not the repository Trail number", "format": "int64", "type": "integer" }, "path": { "description": "API-relative parent detail path in the project's cell", "type": "string" }, "primary_processing_cell": { "description": "Project cell ID from Core; empty when unassigned (do not infer from the repository)", "type": "string" }, "project": { "description": "Canonical public project name, never its internal storage name", "type": "string" }, "project_id": { "type": "string" }, "url": { "description": "Web app page for the parent Trail; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "id", "number", "project_id", "host", "project", "path", "jurisdiction", "primary_processing_cell" ], "type": "object" }, "TrailPersonResponse": { "additionalProperties": false, "properties": { "accountId": { "type": "string" }, "avatarUrl": { "type": "string" }, "displayName": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "login": { "type": "string" }, "username": { "type": "string" } }, "required": [ "login", "displayName", "identity" ], "type": "object" }, "TrailResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "assigneeAccountIds": { "description": "Account IDs aligned with assignees", "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "assigneeProfiles": { "items": { "$ref": "#/components/schemas/TrailPersonResponse" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailPersonResponse" }, "authorAccountId": { "type": "string" }, "body": { "description": "Markdown until the first editor-backed body write; a plain-text projection thereafter. Rich content is in bodyDocument.", "type": "string" }, "bodyDocument": { "allOf": [ { "description": "Rich body snapshot on detail responses; omitted from lists. No CRDT state." }, { "$ref": "#/components/schemas/TrailBodyDocumentJSON" } ] }, "capabilities": { "$ref": "#/components/schemas/ProjectTrailCapabilitiesResponse" }, "changes": { "description": "Authorized Changes with database-backed readiness; no live mergeability checks", "items": { "$ref": "#/components/schemas/ProjectTrailChangeReadiness" }, "type": "array" }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "isPossiblyPartial": { "description": "True when access filtering means repoIds or changes must not be interpreted as a complete aggregate; this is conservative and does not indicate that any item was omitted", "type": "boolean" }, "lastActivityAt": { "description": "Latest meaningful activity on this Trail or an independently readable Change; excludes background bookkeeping", "type": "string" }, "lastVisitedAt": { "description": "Caller's last platform read; null if never visited, unavailable, or caller is not an account", "format": "date-time", "type": [ "string", "null" ] }, "metadata": { "additionalProperties": {}, "type": "object" }, "metadataUpdatedAt": { "description": "When this Trail's own fields last changed; use the response ETag for If-Match", "type": "string" }, "number": { "format": "int64", "type": "integer" }, "phase": { "description": "Derived project lifecycle phase; closed follows the project Trail status, while other phases inherit repository Change progress", "enum": [ "planning", "building", "complete", "closed" ], "type": "string" }, "priority": { "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "project": { "$ref": "#/components/schemas/GlobalTrailProjectResponse" }, "projectId": { "type": "string" }, "repoIds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "enum": [ "open", "closed" ], "type": "string" }, "title": { "type": "string" }, "type": { "enum": [ "bug", "feature", "task" ], "type": "string" }, "url": { "description": "Web app page for this Trail; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "id", "projectId", "number", "title", "body", "status", "phase", "metadata", "type", "priority", "assignees", "assigneeAccountIds", "repoIds", "authorAccountId", "createdAt", "metadataUpdatedAt", "closedAt", "lastVisitedAt", "lastActivityAt" ], "type": "object" }, "TrailRestoreBranchResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailRestoreBranchResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "branch": { "description": "The restored branch, without refs/heads/", "type": "string" }, "commit_sha": { "description": "The commit the branch points at: the Trail's saved head", "type": "string" } }, "required": [ "branch", "commit_sha" ], "type": "object" }, "TrailReviewer": { "additionalProperties": false, "properties": { "actor_account_id": { "type": "string" }, "identity": { "$ref": "#/components/schemas/ContributorIdentity" }, "is_approval_stale": { "type": "boolean" }, "login": { "type": "string" }, "status": { "type": "string" } }, "required": [ "login", "status", "identity" ], "type": "object" }, "TrailRunResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailRunResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "result": { "$ref": "#/components/schemas/RunnerResultJSON" }, "run": { "$ref": "#/components/schemas/RunnerRunJSON" } }, "required": [ "run", "result" ], "type": "object" }, "TrailRunnerItemJSON": { "additionalProperties": false, "properties": { "evaluated_at_sha": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "run_id": { "type": [ "string", "null" ] }, "runner_id": { "type": "string" }, "stale_reason": { "type": [ "string", "null" ] }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "state": { "type": "string" } }, "required": [ "runner_id", "state", "outcome", "run_id", "evaluated_at_sha", "started_at", "stale_reason" ], "type": "object" }, "TrailSettingsBody": { "additionalProperties": false, "properties": { "trails_enabled": { "type": "boolean" } }, "required": [ "trails_enabled" ], "type": "object" }, "TrailSettingsInputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailSettingsInputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "trails_enabled": { "type": "boolean" } }, "type": "object" }, "TrailSettingsOutputBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailSettingsOutputBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "settings": { "$ref": "#/components/schemas/TrailSettingsBody" } }, "required": [ "settings" ], "type": "object" }, "TrailStackJSON": { "additionalProperties": false, "properties": { "base": { "description": "The stack's target branch, which every stacked merge lands on. Empty when the forge did not report it.", "type": "string" }, "position": { "description": "1-based index of this trail's proposal in pull_requests.", "format": "int64", "type": "integer" }, "pull_requests": { "description": "Bottom of the stack (closest to the base branch) first.", "items": { "$ref": "#/components/schemas/TrailStackPullRequestJSON" }, "type": [ "array", "null" ] }, "size": { "format": "int64", "type": "integer" } }, "required": [ "position", "size", "pull_requests" ], "type": "object" }, "TrailStackPullRequestJSON": { "additionalProperties": false, "properties": { "current": { "type": "boolean" }, "pr_number": { "format": "int64", "type": "integer" }, "status": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "trail_number": { "description": "Null when no trail in this repo links the pull request.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "pr_number", "trail_number", "title", "status", "current" ], "type": "object" }, "TrailStackResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailStackResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "stack": { "allOf": [ { "description": "Null when the trail has no change proposal, the repo is not a GitHub mirror, the proposal is in no stack, or the forge read failed." }, { "$ref": "#/components/schemas/TrailStackJSON" } ] } }, "required": [ "stack" ], "type": "object" }, "TrailTimelineResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailTimelineResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "commitCount": { "format": "int64", "type": "integer" }, "incomplete": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/TimelineEvent" }, "type": [ "array", "null" ] }, "nextPageToken": { "type": "string" } }, "required": [ "items", "incomplete" ], "type": "object" }, "TrailUpdateBody": { "additionalProperties": false, "properties": { "assignees": {}, "base": {}, "body": {}, "branch": {}, "priority": {}, "ready_for_review": {}, "requested_reviewers": {}, "status": {}, "title": {}, "type": {} }, "type": "object" }, "TrailUpdateBranchResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailUpdateBranchResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "mergeCommitSha": { "description": "Resulting Trail branch head SHA (also populated for fast-forward updates)", "type": "string" } }, "required": [ "mergeCommitSha" ], "type": "object" }, "TrailUpdateJSON": { "additionalProperties": false, "properties": { "base_sha": { "type": [ "string", "null" ] }, "head_sha": { "type": [ "string", "null" ] }, "merge_base_sha": { "type": [ "string", "null" ] } }, "required": [ "merge_base_sha", "base_sha", "head_sha" ], "type": "object" }, "TrailUpdateRequestJSON": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailUpdateRequestJSON.json" ], "format": "uri", "readOnly": true, "type": "string" }, "assignees": { "items": { "oneOf": [ { "description": "An actor reference: ulid:\u003caccount id\u003e or @username. A bare string is a GitHub login (legacy).", "type": "string" }, { "properties": { "actor_account_id": { "description": "An Entire account ULID.", "type": "string" } }, "required": [ "actor_account_id" ], "type": "object" } ] }, "type": "array" }, "base": { "minLength": 1, "type": "string" }, "branch": { "type": [ "string", "null" ] }, "priority": { "enum": [ "urgent", "high", "medium", "low", "none" ], "type": "string" }, "ready_for_review": { "type": "boolean" }, "status": { "enum": [ "open", "merged", "closed" ], "type": "string" }, "title": { "minLength": 1, "type": "string" }, "type": { "enum": [ "bug", "feature", "task" ], "type": "string" } }, "type": "object" }, "TrailUpdateResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailUpdateResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "trail": { "$ref": "#/components/schemas/TrailUpdateJSON" } }, "required": [ "trail" ], "type": "object" }, "TrailWatchersBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailWatchersBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "watchers": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "watchers" ], "type": "object" }, "TrailWriteJSON": { "additionalProperties": false, "properties": { "assignee_identities": { "items": { "$ref": "#/components/schemas/TrailAssigneeIdentity" }, "type": [ "array", "null" ] }, "assignees": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "author": { "$ref": "#/components/schemas/TrailAuthor" }, "base": { "type": "string" }, "body_document": { "$ref": "#/components/schemas/TrailBodyDocumentJSON" }, "branch": { "type": [ "string", "null" ] }, "checkpoint_count": { "format": "int64", "type": "integer" }, "comment_count": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "has_code_changes": { "type": "boolean" }, "id": { "type": "string" }, "last_activity_at": { "description": "Latest meaningful activity on the Change; excludes background bookkeeping and falls back to created_at until activity is recorded.", "format": "date-time", "type": "string" }, "merged_at": { "format": "date-time", "type": [ "string", "null" ] }, "number": { "format": "int64", "type": "integer" }, "original_branch": { "type": [ "string", "null" ] }, "parent": { "allOf": [ { "description": "Discoverable project parent on list/detail reads; absence does not prove the work is parentless" }, { "$ref": "#/components/schemas/TrailParentReference" } ] }, "phase": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "ready_for_review": { "type": "boolean" }, "reviewers": { "items": { "$ref": "#/components/schemas/TrailReviewer" }, "type": [ "array", "null" ] }, "status": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "unresolved_count": { "format": "int64", "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "description": "Web app page for this code work; absent when this deployment has no frontend origin", "type": "string" } }, "required": [ "checkpoint_count", "body_document", "id", "number", "title", "status", "branch", "original_branch", "base", "type", "priority", "author", "assignees", "assignee_identities", "reviewers", "ready_for_review", "has_code_changes", "comment_count", "unresolved_count", "created_at", "updated_at", "merged_at", "last_activity_at", "phase" ], "type": "object" }, "TrailsGateRecomputeResponseBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailsGateRecomputeResponseBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "blocking_failures": { "items": { "$ref": "#/components/schemas/GateResult" }, "type": [ "array", "null" ] }, "changed": { "type": "boolean" }, "evaluated_at": { "format": "date-time", "type": [ "string", "null" ] }, "gates": { "items": { "$ref": "#/components/schemas/GateResult" }, "type": [ "array", "null" ] }, "gates_enabled": { "type": "boolean" }, "head_sha": { "type": [ "string", "null" ] }, "mergeable": { "description": "Whether the evaluated gates allow merging. Does not include merge conflicts or guarantee fresh CI evidence. Use /mergeability for current merge readiness.", "type": "boolean" } }, "required": [ "changed", "gates_enabled", "head_sha", "gates", "blocking_failures", "mergeable", "evaluated_at" ], "type": "object" }, "TrailsLinkedBranchesBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailsLinkedBranchesBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "TrailsListResponse": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailsListResponse.json" ], "format": "uri", "readOnly": true, "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/TrailListItem" }, "type": [ "array", "null" ] }, "next_cursor": { "type": "string" }, "total_count": { "format": "int64", "type": "integer" } }, "required": [ "items", "total_count" ], "type": "object" }, "TrailsStatsBody": { "additionalProperties": false, "properties": { "$schema": { "description": "A URL to the JSON Schema for this object.", "examples": [ "/api/v1/schemas/TrailsStatsBody.json" ], "format": "uri", "readOnly": true, "type": "string" }, "closed": { "format": "int64", "type": "integer" }, "draft": { "format": "int64", "type": "integer" }, "merged": { "format": "int64", "type": "integer" }, "open": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" }, "window": { "allOf": [ { "description": "Trails created or merged in [since, until]; present only when since or until is set." }, { "$ref": "#/components/schemas/TrailActivity" } ] } }, "required": [ "draft", "open", "merged", "closed", "total" ], "type": "object" }, "TranscriptImage": { "additionalProperties": false, "properties": { "data": { "type": "string" }, "mediaType": { "type": "string" } }, "required": [ "mediaType", "data" ], "type": "object" }, "TranscriptMessage": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "id": { "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/TranscriptImage" }, "type": [ "array", "null" ] }, "role": { "type": "string" }, "runtimeTags": { "items": { "$ref": "#/components/schemas/TranscriptRuntimeTag" }, "type": [ "array", "null" ] }, "skillInvocation": { "$ref": "#/components/schemas/TranscriptSkillInvocation" }, "timestamp": { "type": "string" }, "toolCalls": { "items": { "$ref": "#/components/schemas/ToolCall" }, "type": [ "array", "null" ] } }, "required": [ "id", "role", "content", "timestamp" ], "type": "object" }, "TranscriptRuntimeTag": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "tag": { "type": "string" } }, "required": [ "tag", "content" ], "type": "object" }, "TranscriptSkillInvocation": { "additionalProperties": false, "properties": { "collapseTarget": { "type": "string" }, "defaultCollapsed": { "type": "boolean" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "label": { "type": "string" }, "skillName": { "type": "string" }, "source": { "$ref": "#/components/schemas/TranscriptSkillSource" } }, "required": [ "eventType", "skillName" ], "type": "object" }, "TranscriptSkillSource": { "additionalProperties": false, "properties": { "agent": { "type": "string" }, "confidence": { "type": "string" }, "signal": { "type": "string" } }, "type": "object" }, "URL": { "format": "uri", "type": [ "string", "null" ] }, "UploadInfoJSON": { "additionalProperties": false, "properties": { "expiresAt": { "type": "string" }, "maxBytes": { "format": "int64", "type": "integer" }, "url": { "type": "string" } }, "required": [ "url", "expiresAt", "maxBytes" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "JWT", "description": "Bearer token authorizing this operation's repository action. Each operation's security requirement names the resource action the token must be authorized for (pull or push).", "scheme": "bearer", "type": "http" }, "workloadMTLS": { "description": "Internal workload mTLS. Commit construction requires the entire-api SPIFFE identity.", "type": "mutualTLS" }, "pluginWebhookToken": { "bearerFormat": "JWT", "description": "EdDSA JWT signed by the delivering cell. `iss` is that cell's origin: check it against the cells you trust, then resolve the token's `kid` at `{iss}/.well-known/jwks.json`. `aud` is your plugin slug. Check `iat` and `exp`; a token lives 5 minutes. `body_sha256` is the unpadded base64url SHA-256 of the exact request body bytes; check it before parsing. Each attempt carries a new token and `jti`.", "scheme": "bearer", "type": "http" }, "oauth2": { "description": "OAuth 2.0 authorization code flow.", "flows": { "authorizationCode": { "authorizationUrl": "https://us.auth.entire.io/authorize", "scopes": { "offline_access": "Stay signed in and receive a refresh token.", "openid": "Verify your identity." }, "tokenUrl": "https://us.auth.entire.io/oauth/token" } }, "type": "oauth2" }, "oidc": { "description": "OpenID Connect discovery document: https://us.auth.entire.io/.well-known/openid-configuration", "openIdConnectUrl": "https://us.auth.entire.io/.well-known/openid-configuration", "type": "openIdConnect" } }, "headers": { "AgentInsightsVersion": { "description": "The commit the serving image was built from (see the API description).", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Caller has no grant for the repo (existence is never disclosed before authorization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotInRegion": { "description": "Repo not in this region (its placement lives in another cell)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MemoryNotFound": { "description": "No such fact in this repo, or repo not in this region", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MemoryConflict": { "description": "The fact is no longer active (concurrently superseded or retracted); refresh and re-apply the draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Internal": { "description": "Internal error (message redacted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "Auth or repo access temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "RepoID": { "name": "repo_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "FactID": { "name": "fact_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fact:[0-9a-f]{24}$" }, "description": "Content-derived fact id (factmerge.RecordID shape)." }, "PageSize": { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Out-of-range values are clamped (below 1 to 50, above 100 to 100), never rejected." }, "PageToken": { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a prior nextPageToken. An unparseable or stale token is a 400 (restart without a token), never a silent first page." } } }, "tags": [ { "name": "search", "description": "Operations under the /search surface." }, { "name": "semantic-search", "description": "Operations under the /semantic-search surface." }, { "name": "brainstore", "description": "Operations served by the brainstore service." }, { "description": "The authenticated caller's own cross-repo activity, commits, checkpoints, sessions, and recap.", "name": "me" }, { "description": "Residency-aware previews of the caller's surface, served under /experimental. Shapes may change without notice.", "name": "experimental" }, { "description": "Per-user settings: pinned and recent repos, diff view, and saved filter tabs.", "name": "preferences" }, { "description": "Repository discovery list, metadata, and headline rollups (summary, activity, contributors, agents).", "name": "repos" }, { "description": "Git browsing for a repo: commits, commit detail, branch compare, tree listings, raw file bytes, and branches.", "name": "code" }, { "description": "Checkpoint listing, resolution, LLM analysis, transcripts, and per-repo checkpoint status.", "name": "checkpoints" }, { "description": "Materialised sessions: listing, detail, transcripts, rename, and the public-share toggle.", "name": "sessions" }, { "description": "Repo dashboard aggregates under /overview: commit and checkpoint stats, contributor breakdowns, and session patterns.", "name": "overview" }, { "description": "Live ref-change stream for a repo (SSE).", "name": "refs" }, { "description": "Trails themselves: list, create, read, update, delete, plus per-repo counts, claimed branches, and the body-document ensure.", "name": "trails" }, { "description": "What has happened on a trail: the merged timeline, the event stream, and who is watching (per trail, plus a repo-wide roll-up).", "name": "trail-activity" }, { "description": "Conversation on a trail: discussions, their messages, and the live discussion-event stream.", "name": "trail-discussions" }, { "description": "Code review on a trail: review state, comments, diffs, reviewed files, and review re-runs.", "name": "trail-reviews" }, { "description": "Runner output on a trail: the latest result per configured runner, monitor results, and manual launches.", "name": "trail-runs" }, { "description": "Quality gates: repo gate definitions, gate settings, repo-authored monitor definitions, and a trail's gate evaluation.", "name": "trail-gates" }, { "description": "Getting a trail landed: approval decisions, merge readiness, and the merge itself.", "name": "trail-approvals" }, { "description": "Trail attachment blobs: upload intent, completion, retrieval, and deletion.", "name": "trail-attachments" }, { "description": "Project-scoped Trails, and their owned repository Changes and discussions.", "name": "projects" }, { "description": "Agent-provenance ranking for a repo's code scopes.", "name": "experts" }, { "description": "git-meta-compatible repo metadata read and write (git is the source of truth).", "name": "git-meta" }, { "description": "A project's versioned agents — what each runs (its own runner or an Entire preset), what it is called, the environment it runs in, the repositories it reviews and its trigger — and Entire's presets. Saving one runs nothing.", "name": "agents" }, { "description": "A project's saved, versioned Environments — where an agent runs: provider and sandbox lifetime — reusable across the project's repositories and agents. Configuration only: saving one provisions nothing.", "name": "environments" }, { "description": "Runs of a project's agents, each on one Change: starting one, the immutable snapshot each captured, status, output and results, retry and cancel.", "name": "runs" }, { "description": "Mutating repo configuration: runner, trail, public-sharing, and gate-enforcement settings (requires repo manage_settings for every forge).", "name": "repo-settings" }, { "description": "The caller's open pull requests across their repositories.", "name": "pull-requests" }, { "description": "Service-authed only: editor-document sync behind the trail body editor.", "name": "trails-internal" }, { "description": "The runner OIDC issuer's discovery document and JWKS. Machine-consumed.", "name": "runner-issuer" } ], "security": [ { "bearerAuth": [] } ] }