{ "openapi": "3.1.0", "info": { "title": "ultrareview API", "version": "1.0.0", "summary": "Scoped, machine-first control over how ultrareview reviews your code.", "description": "This API lets a program change how ultrareview reviews your code: which profile runs, how strict it is,\nand which repositories get what. It edits the same settings as the dashboard, with the same checks, and\nevery change is recorded against the token that made it.\n\nIt is built so an agent can use it without a person watching. Every refusal comes with a short code and a\nplain sentence saying what to do next. Add `?dryRun=1` to any write to see exactly what would happen\nwithout changing anything.\n\nIt does not expose reviews, findings or transcripts, cannot read or set your model provider keys, and\ncannot create or revoke tokens. Those stay in the dashboard, behind your login.\n\nOnly the public pages (this one, the root, the health check and the catalog) can be read from a browser.\nAnything that takes a token refuses browser requests (no CORS headers), so a web page can never spend\nyour credential.", "contact": { "name": "mobsession", "url": "https://mobsession.ai/docs/api-tokens" } }, "externalDocs": { "url": "https://mobsession.ai/docs/api-tokens", "description": "The documentation for humans, including how to mint and revoke a token." }, "servers": [ { "url": "https://api.mobsession.ai", "description": "Production" } ], "security": [ { "bearerToken": [] } ], "tags": [ { "name": "Meta", "description": "What this API is, what your token may do, and whether it is up. None of these need a scope." }, { "name": "Profiles", "description": "Named sets of review instructions: what a review looks for, how hard it works, and how much it is allowed to say." }, { "name": "Repositories", "description": "Per-repository review settings, and the effective values a review would actually use." }, { "name": "Settings", "description": "The organization-wide posture every repository inherits." } ], "paths": { "/": { "get": { "operationId": "getRoot", "summary": "API root", "description": "A tiny, stable document naming the API, where its documentation lives, and which versions exist. It is the one URL that will not move, so it is the safe thing to hard-code and the safe thing to poll.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "The root document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Root" }, "example": { "name": "ultrareview API", "docs": "https://mobsession.ai/docs/api-tokens", "versions": [ { "version": "v1", "status": "current", "catalog": "https://api.mobsession.ai/v1", "openapi": "https://api.mobsession.ai/v1/openapi.json" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/health": { "get": { "operationId": "getHealth", "summary": "Health check", "description": "Whether reviews are being processed. \"Is the server answering\" is a question you already answered by getting a response at all, so this reports the thing worth monitoring instead: work is being picked up.\n\nIt answers 200 while processing is healthy and 503 when it is not, so a monitor that only reads status codes still sees an outage. `components.reviewProcessing` carries the same verdict for a monitor that reads bodies.\n\nIt reports nothing else. No counts, no identifiers, no versions, no names of anything: what exactly is degraded is an internal question, and this endpoint is public.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "Reviews are being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "status": "ok", "components": { "reviewProcessing": "ok" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "Reviews are not being processed. The body says the same thing, for a monitor that reads bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "status": "degraded", "components": { "reviewProcessing": "degraded" } } } } } } } }, "/v1": { "get": { "operationId": "getCatalog", "summary": "Version catalog", "description": "Everything an agent needs to use v1 without reading a word of prose: every endpoint with the scope it needs, the scope catalog, the error codes and the status each answers with, the rate limits, and how dry runs work. Generated from the same OpenAPI document you are reading, so it can never describe an endpoint that does not exist.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "OpenAPI document", "description": "This document, served by the deployment you are talking to, with `servers` pointing back at that deployment. Feed it to a client generator, or to whatever reads specifications where you work.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/token": { "get": { "operationId": "getToken", "summary": "The token you are using", "description": "What the token you just presented may do, and how long it has left. Worth calling at the start of a job: an agent can confirm it holds the scopes it needs and has time to finish, rather than discovering an expiry as a failed write halfway through. Any valid token may call this; no scope is required.", "tags": [ "Meta" ], "responses": { "200": { "description": "The token's own context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenContext" }, "example": { "label": "release-bot", "org": "org_2fQx7zLp", "scopes": [ "settings:read", "settings:write" ], "expiresAt": 1763466000000 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/profiles": { "get": { "operationId": "listProfiles", "summary": "List review profiles", "description": "Every profile this organization can use: the built-ins that ship with ultrareview and the ones your organization authored. Authoring a profile with a built-in's name shadows it, and only the shadowing one appears. Which profile is the default is on `GET /v1/settings`; which profile a repository is pinned to is on `GET /v1/repos`.", "tags": [ "Profiles" ], "x-required-scope": "profiles:read", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of profiles, ordered by name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileList" }, "example": { "data": [ { "name": "strict-security", "description": "Security first, and it argues with itself before it speaks.", "dimensions": [ "security", "correctness" ], "model": "claude-opus-4-8", "effort": "high", "severityFloor": "nit", "maxComments": 30, "maxOpenCommentsPerPr": 40, "inlineFloor": "major", "incrementInlineFloor": "major", "verificationStrictness": 2, "verifyMode": "screen-then-panel", "remedyPolicy": "label", "tone": "balanced", "memoryScope": "repo", "autofix": false } ], "hasMore": false, "nextCursor": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createProfile", "summary": "Create a review profile", "description": "Authors a new profile. Only `name` and `dimensions` are required; everything else has a default, and the response shows the complete profile with those defaults filled in, so you never have to guess what you got. Naming it after a built-in is allowed and shadows that built-in.", "tags": [ "Profiles" ], "x-required-scope": "profiles:write", "parameters": [ { "$ref": "#/components/parameters/dryRun" } ], "requestBody": { "required": true, "description": "The profile to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "examples": { "minimal": { "summary": "The least you can send", "value": { "name": "docs-watch", "dimensions": [ "docs" ] } }, "tuned": { "summary": "A profile with its knobs set", "value": { "name": "payments-guard", "dimensions": [ "security", "correctness" ], "effort": "high", "verificationStrictness": 2 } } } } } }, "responses": { "200": { "description": "A dry run. The profile that WOULD have been created, and nothing written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileWrite" }, "example": { "dryRun": true, "name": "strict-security", "description": "Security first, and it argues with itself before it speaks.", "dimensions": [ "security", "correctness" ], "model": "claude-opus-4-8", "effort": "high", "severityFloor": "nit", "maxComments": 30, "maxOpenCommentsPerPr": 40, "inlineFloor": "major", "incrementInlineFloor": "major", "verificationStrictness": 2, "verifyMode": "screen-then-panel", "remedyPolicy": "label", "tone": "balanced", "memoryScope": "repo", "autofix": false, "builtIn": false } } } }, "201": { "description": "Created. `Location` names the new profile.", "headers": { "Location": { "description": "The new profile's URL.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileWrite" }, "example": { "dryRun": false, "name": "strict-security", "description": "Security first, and it argues with itself before it speaks.", "dimensions": [ "security", "correctness" ], "model": "claude-opus-4-8", "effort": "high", "severityFloor": "nit", "maxComments": 30, "maxOpenCommentsPerPr": 40, "inlineFloor": "major", "incrementInlineFloor": "major", "verificationStrictness": 2, "verifyMode": "screen-then-panel", "remedyPolicy": "label", "tone": "balanced", "memoryScope": "repo", "autofix": false, "builtIn": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/profiles/{name}": { "get": { "operationId": "getProfile", "summary": "Read one profile", "description": "One profile by name, built-in or authored, with every default filled in. The name is matched without regard to case.", "tags": [ "Profiles" ], "x-required-scope": "profiles:read", "parameters": [ { "$ref": "#/components/parameters/profileName" } ], "responses": { "200": { "description": "The profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRead" }, "example": { "name": "strict-security", "description": "Security first, and it argues with itself before it speaks.", "dimensions": [ "security", "correctness" ], "model": "claude-opus-4-8", "effort": "high", "severityFloor": "nit", "maxComments": 30, "maxOpenCommentsPerPr": 40, "inlineFloor": "major", "incrementInlineFloor": "major", "verificationStrictness": 2, "verifyMode": "screen-then-panel", "remedyPolicy": "label", "tone": "balanced", "memoryScope": "repo", "autofix": false, "builtIn": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateProfile", "summary": "Update a profile", "description": "Changes some fields of one authored profile, renaming included. Fields you leave out keep their values. Built-ins cannot be edited in place; author a profile with the same name to shadow one.", "tags": [ "Profiles" ], "x-required-scope": "profiles:write", "parameters": [ { "$ref": "#/components/parameters/profileName" }, { "$ref": "#/components/parameters/dryRun" } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilePatch" }, "example": { "effort": "high", "severityFloor": "minor" } } } }, "responses": { "200": { "description": "The profile as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileWrite" }, "example": { "dryRun": false, "name": "strict-security", "description": "Security first, and it argues with itself before it speaks.", "dimensions": [ "security", "correctness" ], "model": "claude-opus-4-8", "effort": "high", "severityFloor": "nit", "maxComments": 30, "maxOpenCommentsPerPr": 40, "inlineFloor": "major", "incrementInlineFloor": "major", "verificationStrictness": 2, "verifyMode": "screen-then-panel", "remedyPolicy": "label", "tone": "balanced", "memoryScope": "repo", "autofix": false, "builtIn": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteProfile", "summary": "Delete a profile", "description": "Removes one authored profile. Refused while a repository pin or an organization lock still points at it, and the refusal names what is still pointing, so you know what to change first. Built-ins always exist and cannot be deleted.", "tags": [ "Profiles" ], "x-required-scope": "profiles:write", "parameters": [ { "$ref": "#/components/parameters/profileName" }, { "$ref": "#/components/parameters/dryRun" } ], "responses": { "200": { "description": "Deleted, or reported as deletable on a dry run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "deleted": { "type": "string", "description": "The name of the profile that was removed." } }, "required": [ "dryRun", "deleted" ] }, "example": { "dryRun": false, "deleted": "strict-security" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/profiles/{name}/apply": { "post": { "operationId": "applyProfile", "summary": "Apply a profile", "description": "Makes a profile the organization default, or pins it to one repository. A token with only `profiles:apply` can switch profiles and touch nothing else. The response is whatever changed: the organization settings for a default, the repository for a pin.", "tags": [ "Profiles" ], "x-required-scope": "profiles:apply", "parameters": [ { "$ref": "#/components/parameters/profileName" }, { "$ref": "#/components/parameters/dryRun" } ], "requestBody": { "required": true, "description": "Where to apply it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyProfileRequest" }, "examples": { "orgDefault": { "summary": "Make it the organization default", "value": { "target": "org-default" } }, "repo": { "summary": "Pin it to one repository", "value": { "target": "repo", "repo": "acme/storefront" } } } } } }, "responses": { "200": { "description": "The resource that changed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OrgSettingsWrite" }, { "$ref": "#/components/schemas/RepoWrite" } ] }, "examples": { "orgDefault": { "summary": "After an org-default apply", "value": { "dryRun": false, "defaultProfile": "strict-security", "blockingPolicy": "advisory", "reviewScope": "changes-only", "requireVerifiedSuggestions": false, "ignore": [ "**/pnpm-lock.yaml", "**/*.min.js" ], "routing": [ { "when": { "paths": [ "packages/payments/**" ] }, "use": "strict-security" } ], "rulePacks": [], "memory": null, "updatedAt": 1755690000000 } }, "repo": { "summary": "After a repository pin", "value": { "dryRun": false, "id": "574128390", "owner": "acme", "name": "storefront", "fullName": "acme/storefront", "settings": { "autoReview": "on", "reviewOnPush": null, "profileName": "strict-security", "routing": null, "requireVerifiedSuggestions": null, "maxReviewFiles": 800, "maxReviewDiffLines": null, "watchedPaths": null, "workerTier": null, "fixPullRequests": null, "updatedBy": "api-token:k1748ab0000", "updatedAt": 1755690000000, "version": 4 }, "effective": { "profileName": "strict-security", "maxReviewFiles": 800, "maxReviewDiffLines": 40000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/repos": { "get": { "operationId": "listRepos", "summary": "List connected repositories", "description": "The repositories this organization has connected, each with the part of its review policy you are most likely to be looking for: whether it reviews automatically, and which profile it is pinned to. Disconnected repositories are not listed, because the API cannot act on them.", "tags": [ "Repositories" ], "x-required-scope": "settings:read", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "One page of repositories, ordered by `fullName`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoList" }, "example": { "data": [ { "id": "574128390", "owner": "acme", "name": "storefront", "fullName": "acme/storefront", "autoReview": "on", "profileName": "strict-security", "version": 4 } ], "hasMore": false, "nextCursor": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/repos/{owner}/{repo}": { "get": { "operationId": "getRepo", "summary": "Read one repository's review settings", "description": "One repository's own settings, the version to send back with your next write, and the effective values a review would actually use. The effective block is what makes a null above readable: it tells you what an unset field resolves to rather than leaving you to guess.", "tags": [ "Repositories" ], "x-required-scope": "settings:read", "parameters": [ { "$ref": "#/components/parameters/owner" }, { "$ref": "#/components/parameters/repo" } ], "responses": { "200": { "description": "The repository.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Repo" }, "example": { "id": "574128390", "owner": "acme", "name": "storefront", "fullName": "acme/storefront", "settings": { "autoReview": "on", "reviewOnPush": null, "profileName": "strict-security", "routing": null, "requireVerifiedSuggestions": null, "maxReviewFiles": 800, "maxReviewDiffLines": null, "watchedPaths": null, "workerTier": null, "fixPullRequests": null, "updatedBy": "api-token:k1748ab0000", "updatedAt": 1755690000000, "version": 4 }, "effective": { "profileName": "strict-security", "maxReviewFiles": 800, "maxReviewDiffLines": 40000 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateRepo", "summary": "Update a repository's review settings", "description": "Changes some of one repository's settings. Leave a key out to keep it, send null to go back to inherited or default, send a value to set it. The response is the whole repository as it now stands.", "tags": [ "Repositories" ], "x-required-scope": "settings:write", "parameters": [ { "$ref": "#/components/parameters/owner" }, { "$ref": "#/components/parameters/repo" }, { "$ref": "#/components/parameters/dryRun" } ], "requestBody": { "required": true, "description": "The settings to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoSettingsPatch" }, "examples": { "pinAProfile": { "summary": "Pin a profile and cap the biggest pull request", "value": { "profileName": "strict-security", "maxReviewFiles": 800 } }, "safeWrite": { "summary": "Refuse if it changed since you read it", "value": { "autoReview": "off", "expectedVersion": 4 } }, "clearAnOverride": { "summary": "Go back to inheriting", "value": { "maxReviewFiles": null } }, "routeAFolder": { "summary": "Send one folder to a stricter profile", "value": { "routing": [ { "when": { "paths": [ "auth/**", "billing/**" ] }, "use": "security" } ] } } } } } }, "responses": { "200": { "description": "The repository as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoWrite" }, "example": { "dryRun": false, "id": "574128390", "owner": "acme", "name": "storefront", "fullName": "acme/storefront", "settings": { "autoReview": "on", "reviewOnPush": null, "profileName": "strict-security", "routing": null, "requireVerifiedSuggestions": null, "maxReviewFiles": 800, "maxReviewDiffLines": null, "watchedPaths": null, "workerTier": null, "fixPullRequests": null, "updatedBy": "api-token:k1748ab0000", "updatedAt": 1755690000000, "version": 4 }, "effective": { "profileName": "strict-security", "maxReviewFiles": 800, "maxReviewDiffLines": 40000 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/settings": { "get": { "operationId": "getSettings", "summary": "Read organization settings", "description": "Everything about how this organization reviews, except the profiles themselves, which have their own endpoints.", "tags": [ "Settings" ], "x-required-scope": "settings:read", "responses": { "200": { "description": "The organization's settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSettings" }, "example": { "defaultProfile": "default", "blockingPolicy": "advisory", "reviewScope": "changes-only", "requireVerifiedSuggestions": false, "ignore": [ "**/pnpm-lock.yaml", "**/*.min.js" ], "routing": [ { "when": { "paths": [ "packages/payments/**" ] }, "use": "strict-security" } ], "rulePacks": [], "memory": null, "updatedAt": 1755690000000 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateSettings", "summary": "Update organization settings", "description": "Replaces the slices you name and leaves the rest alone. A slice is replaced whole: send the `ignore` list you want, not the entries to add. The response is the settings as they now stand.", "tags": [ "Settings" ], "x-required-scope": "settings:write", "parameters": [ { "$ref": "#/components/parameters/dryRun" } ], "requestBody": { "required": true, "description": "The slices to replace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSettingsPatch" }, "examples": { "blocking": { "summary": "Let reviews hold a merge", "value": { "blockingPolicy": "blocking" } }, "ignore": { "summary": "Replace the ignore list", "value": { "ignore": [ "**/pnpm-lock.yaml", "**/dist/**" ] } } } } } }, "responses": { "200": { "description": "The settings as they now stand.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSettingsWrite" }, "example": { "dryRun": false, "defaultProfile": "default", "blockingPolicy": "blocking", "reviewScope": "changes-only", "requireVerifiedSuggestions": false, "ignore": [ "**/pnpm-lock.yaml", "**/*.min.js" ], "routing": [ { "when": { "paths": [ "packages/payments/**" ] }, "use": "strict-security" } ], "rulePacks": [], "memory": null, "updatedAt": 1755690000000 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "bearerToken": { "type": "http", "scheme": "bearer", "description": "A bearer token minted by an org admin in the dashboard, under Configuration and then API tokens. Tokens\nbegin with `urk_`, are shown exactly once, and carry the scopes they were minted with and no others.\n\nSend it on every request:\n\n```\nAuthorization: Bearer urk_...\n```\n\nOnly the token's hash is stored, so a leaked database yields no usable credential, and a revoked token stops\nworking immediately rather than at the end of some cache window." } }, "parameters": { "limit": { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Anything above 100 is refused rather than quietly clamped, so a caller always knows what it asked for.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "cursor": { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` from the previous page, passed back unchanged. Opaque: do not build one yourself.", "schema": { "type": "string" } }, "dryRun": { "name": "dryRun", "in": "query", "required": false, "description": "Runs every check a real write would run and changes nothing. The response is what you would have got, marked `dryRun: true`. Accepts only `1`, `true`, `0` or `false`; anything else is refused rather than treated as false, so a typo can never commit by accident.", "schema": { "type": "string", "enum": [ "1", "true", "0", "false" ] }, "example": "1" }, "profileName": { "name": "name", "in": "path", "required": true, "description": "The profile's name, matched without regard to case. URL-encode it if it contains spaces.", "schema": { "type": "string" }, "example": "strict-security" }, "owner": { "name": "owner", "in": "path", "required": true, "description": "The GitHub owner, as GitHub spells it. Matched without regard to case.", "schema": { "type": "string" }, "example": "acme" }, "repo": { "name": "repo", "in": "path", "required": true, "description": "The GitHub repository name. Matched without regard to case.", "schema": { "type": "string" }, "example": "storefront" } }, "schemas": { "Error": { "type": "object", "title": "Error", "description": "Every refusal looks like this, whatever went wrong.", "properties": { "error": { "type": "object", "description": "The refusal. A successful response never carries this key, so `\"error\" in body` is a safe test.", "properties": { "code": { "type": "string", "enum": [ "token_missing", "token_invalid", "token_revoked", "token_expired", "insufficient_scope", "malformed_json", "invalid_query_parameter", "unsupported_media_type", "not_found", "method_not_allowed", "conflict", "version_conflict", "builtin_profile", "org_config_unreadable", "payload_too_large", "validation_failed", "rate_limited", "internal_error" ], "description": "The stable machine value. Branch on this, never on the message." }, "message": { "type": "string", "description": "A sentence written for whoever has to fix it, and safe to show a person verbatim." }, "details": { "type": "object", "additionalProperties": true, "description": "Whatever would help fix it: the scope that was missing, the keys that were allowed, the milliseconds to wait." }, "docs": { "type": "string", "format": "uri", "description": "Where the documentation for this API lives." }, "requestId": { "type": "string", "description": "Present on a 500 only, and logged with the failure. Quote it to support." } }, "required": [ "code", "message", "docs" ] } }, "required": [ "error" ] }, "Root": { "type": "object", "title": "Root", "properties": { "name": { "type": "string", "description": "What this API is called. It does not change." }, "docs": { "type": "string", "format": "uri", "description": "The documentation for humans." }, "versions": { "type": "array", "description": "Every version this deployment serves. Today there is one.", "items": { "type": "object", "properties": { "version": { "type": "string", "description": "The version's name, which is also its path prefix." }, "status": { "type": "string", "enum": [ "current" ], "description": "`current` is the version to build against." }, "catalog": { "type": "string", "format": "uri", "description": "Where this version's machine catalog lives." }, "openapi": { "type": "string", "format": "uri", "description": "Where this version's OpenAPI document lives." } }, "required": [ "version", "status", "catalog", "openapi" ] } } }, "required": [ "name", "docs", "versions" ] }, "Health": { "type": "object", "title": "Health", "description": "The public health verdict. Two fields, both single words, and nothing that describes the machinery behind them.", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ], "description": "The overall verdict, which is `degraded` exactly when a component is. It matches the status code, so you only need one of the two." }, "components": { "type": "object", "description": "Each thing this endpoint can speak for, in one word each.", "properties": { "reviewProcessing": { "type": "string", "enum": [ "ok", "degraded", "unknown" ], "description": "Whether work is being picked up. `unknown` means this deployment has never processed a review, which is true of every development and preview deployment and is not a fault; a permanently red signal is not a signal." } }, "required": [ "reviewProcessing" ] } }, "required": [ "status", "components" ] }, "Catalog": { "type": "object", "title": "Catalog", "description": "The compact, machine-readable summary of v1. A projection of this OpenAPI document, not a second copy of it.", "properties": { "name": { "type": "string", "description": "What this API is called." }, "version": { "type": "string", "description": "The version this catalog describes." }, "baseUrl": { "type": "string", "format": "uri", "description": "The origin every path below hangs off, derived from the host you asked." }, "docs": { "type": "string", "format": "uri", "description": "The documentation for humans." }, "openapi": { "type": "string", "format": "uri", "description": "Where the full OpenAPI document lives." }, "authentication": { "type": "object", "additionalProperties": true, "description": "How to present a token, where one comes from, and where to ask what yours can do." }, "scopes": { "type": "array", "description": "The whole scope catalog, so an agent can explain to a person exactly what to grant.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scope as it is spelled when a token is minted." }, "summary": { "type": "string", "description": "What holding this scope lets a token do." } }, "required": [ "id", "summary" ] } }, "dryRun": { "type": "string", "description": "How to make any write validate without committing." }, "pagination": { "type": "object", "additionalProperties": true, "description": "The one pagination convention every list endpoint follows." }, "rateLimits": { "type": "object", "additionalProperties": true, "description": "The per-token ceilings, read from the limiter's own constants rather than restated." }, "endpoints": { "type": "array", "description": "Every endpoint with the scope it needs and a one-line summary.", "items": { "type": "object", "properties": { "method": { "type": "string", "description": "The HTTP method, upper case, as it goes on the wire." }, "path": { "type": "string", "description": "The path, with `{param}` placeholders where a value goes." }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The scope this endpoint needs, or null when it needs none." }, "summary": { "type": "string", "description": "One line on what the endpoint does." } }, "required": [ "method", "path", "scope", "summary" ] } }, "errors": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Every error code, and the status it answers with." }, "quickstart": { "type": "string", "description": "A curl command that works as soon as you have a token." } }, "required": [ "name", "version", "baseUrl", "docs", "openapi", "authentication", "scopes", "endpoints", "errors" ] }, "TokenContext": { "type": "object", "title": "TokenContext", "properties": { "label": { "type": "string", "description": "The name an admin gave this token when they minted it." }, "org": { "type": "string", "description": "The organization this token acts as. It can never act outside it." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "profiles:read", "profiles:write", "profiles:apply", "settings:read", "settings:write" ] }, "description": "Exactly what it was minted with. No scope implies another." }, "expiresAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When it stops working, in milliseconds since the epoch. Null means it does not expire." } }, "required": [ "label", "org", "scopes", "expiresAt" ] }, "Profile": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "What you call this profile. Repositories and routing rules refer to it by this name, matched without regard to case or surrounding whitespace." }, "description": { "type": "string", "description": "A sentence for whoever reads the profile list later. The review itself does not use it." }, "dimensions": { "type": "array", "items": { "type": "string", "enum": [ "correctness", "security", "performance", "api-contract", "style", "tests", "docs" ] }, "minItems": 1, "description": "What the review looks for. At least one is required, and each one is a separate pass over the change." }, "model": { "type": "string", "minLength": 1, "default": "claude-opus-4-8", "description": "Which model runs the review. A bare model id and a provider-qualified ref both work verbatim. Whether a ref actually resolves is a review-time question, not a save-time one, so a registry that has not caught up yet can never make your configuration unsavable." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ], "default": "medium", "description": "How hard the review works. Higher effort costs more and finds more." }, "severityFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "nit", "description": "The lowest severity that survives at all. Findings under this bar are recorded for the dashboard and never posted." }, "maxComments": { "type": "integer", "exclusiveMinimum": 0, "default": 30, "description": "The most inline comments a SINGLE run may post." }, "maxOpenCommentsPerPr": { "type": "integer", "exclusiveMinimum": 0, "default": 40, "description": "The most ultrareview inline comments that may be open on one pull request at a time, counted across every run. At the ceiling, a new run moves its lowest-severity findings into the summary instead of opening more threads. Blocking findings always stay inline." }, "inlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The lowest severity that earns its own inline comment. Anything below it is listed in full in the review summary instead: moved, never dropped." }, "incrementInlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The same bar again, applied only to follow-up pushes, so a second push does not re-carpet a pull request with small notes. The opening review is never affected." }, "verificationStrictness": { "type": "number", "enum": [ 0, 1, 2, 3 ], "default": 1, "description": "How many independent critics have to agree with a finding before it posts. Zero posts what the finders produced; three is the most adversarial." }, "maxVerifyCritics": { "type": "integer", "exclusiveMinimum": 0, "description": "A ceiling on critics per group of findings. Leave it unset unless you are deliberately capping cost." }, "verifyMode": { "type": "string", "enum": [ "panel", "screen-then-panel" ], "default": "panel", "description": "How verification is staged. `panel` sends every candidate straight to its own critics. `screen-then-panel` runs one pass over all the candidates first, which is the only place a cross-finding view exists, and kills duplicates and the immaterial before the critics ever see them." }, "remedyPolicy": { "type": "string", "enum": [ "off", "label", "strict" ], "default": "label", "description": "What happens to a suggested fix no critic could vouch for. `label` says so in the comment, `strict` also withholds the one-click apply, and `off` is the old behaviour that shows the suggestion with no caution." }, "maxOutputTokens": { "type": "integer", "minimum": 1000, "maximum": 128000, "description": "The output budget for each agent this profile runs. Unset means a generous default. Set it too small and an agent is truncated mid-answer, which quietly loses its whole dimension." }, "tone": { "type": "string", "enum": [ "terse", "balanced", "mentor" ], "default": "balanced", "description": "How the review talks." }, "rulePacks": { "type": "array", "items": { "type": "string" }, "description": "Names of the organization's rule packs to attach to this profile. The packs themselves live on the organization settings." }, "memoryScope": { "type": "string", "enum": [ "repo", "repo+path", "repo+author" ], "default": "repo", "description": "How widely this profile's learned memory applies: the whole repository, or narrowed to the path or the author it was learned from." }, "autofix": { "type": "boolean", "const": false, "default": false, "description": "Reserved. Always false in v1." } }, "required": [ "name", "dimensions" ], "additionalProperties": false, "title": "Profile", "description": "A named set of instructions for how a review is run: what it looks for, how hard it works, and how much it is allowed to say." }, "ProfileRead": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "What you call this profile. Repositories and routing rules refer to it by this name, matched without regard to case or surrounding whitespace." }, "description": { "type": "string", "description": "A sentence for whoever reads the profile list later. The review itself does not use it." }, "dimensions": { "type": "array", "items": { "type": "string", "enum": [ "correctness", "security", "performance", "api-contract", "style", "tests", "docs" ] }, "minItems": 1, "description": "What the review looks for. At least one is required, and each one is a separate pass over the change." }, "model": { "type": "string", "minLength": 1, "default": "claude-opus-4-8", "description": "Which model runs the review. A bare model id and a provider-qualified ref both work verbatim. Whether a ref actually resolves is a review-time question, not a save-time one, so a registry that has not caught up yet can never make your configuration unsavable." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ], "default": "medium", "description": "How hard the review works. Higher effort costs more and finds more." }, "severityFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "nit", "description": "The lowest severity that survives at all. Findings under this bar are recorded for the dashboard and never posted." }, "maxComments": { "type": "integer", "exclusiveMinimum": 0, "default": 30, "description": "The most inline comments a SINGLE run may post." }, "maxOpenCommentsPerPr": { "type": "integer", "exclusiveMinimum": 0, "default": 40, "description": "The most ultrareview inline comments that may be open on one pull request at a time, counted across every run. At the ceiling, a new run moves its lowest-severity findings into the summary instead of opening more threads. Blocking findings always stay inline." }, "inlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The lowest severity that earns its own inline comment. Anything below it is listed in full in the review summary instead: moved, never dropped." }, "incrementInlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The same bar again, applied only to follow-up pushes, so a second push does not re-carpet a pull request with small notes. The opening review is never affected." }, "verificationStrictness": { "type": "number", "enum": [ 0, 1, 2, 3 ], "default": 1, "description": "How many independent critics have to agree with a finding before it posts. Zero posts what the finders produced; three is the most adversarial." }, "maxVerifyCritics": { "type": "integer", "exclusiveMinimum": 0, "description": "A ceiling on critics per group of findings. Leave it unset unless you are deliberately capping cost." }, "verifyMode": { "type": "string", "enum": [ "panel", "screen-then-panel" ], "default": "panel", "description": "How verification is staged. `panel` sends every candidate straight to its own critics. `screen-then-panel` runs one pass over all the candidates first, which is the only place a cross-finding view exists, and kills duplicates and the immaterial before the critics ever see them." }, "remedyPolicy": { "type": "string", "enum": [ "off", "label", "strict" ], "default": "label", "description": "What happens to a suggested fix no critic could vouch for. `label` says so in the comment, `strict` also withholds the one-click apply, and `off` is the old behaviour that shows the suggestion with no caution." }, "maxOutputTokens": { "type": "integer", "minimum": 1000, "maximum": 128000, "description": "The output budget for each agent this profile runs. Unset means a generous default. Set it too small and an agent is truncated mid-answer, which quietly loses its whole dimension." }, "tone": { "type": "string", "enum": [ "terse", "balanced", "mentor" ], "default": "balanced", "description": "How the review talks." }, "rulePacks": { "type": "array", "items": { "type": "string" }, "description": "Names of the organization's rule packs to attach to this profile. The packs themselves live on the organization settings." }, "memoryScope": { "type": "string", "enum": [ "repo", "repo+path", "repo+author" ], "default": "repo", "description": "How widely this profile's learned memory applies: the whole repository, or narrowed to the path or the author it was learned from." }, "autofix": { "type": "boolean", "const": false, "default": false, "description": "Reserved. Always false in v1." }, "builtIn": { "type": "boolean", "description": "True for a profile that ships with ultrareview, false for one your organization authored." } }, "required": [ "name", "dimensions", "builtIn" ], "additionalProperties": false, "title": "Profile", "description": "A named set of instructions for how a review is run: what it looks for, how hard it works, and how much it is allowed to say." }, "ProfilePatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "What you call this profile. Repositories and routing rules refer to it by this name, matched without regard to case or surrounding whitespace." }, "description": { "type": "string", "description": "A sentence for whoever reads the profile list later. The review itself does not use it." }, "dimensions": { "type": "array", "items": { "type": "string", "enum": [ "correctness", "security", "performance", "api-contract", "style", "tests", "docs" ] }, "minItems": 1, "description": "What the review looks for. At least one is required, and each one is a separate pass over the change." }, "model": { "type": "string", "minLength": 1, "default": "claude-opus-4-8", "description": "Which model runs the review. A bare model id and a provider-qualified ref both work verbatim. Whether a ref actually resolves is a review-time question, not a save-time one, so a registry that has not caught up yet can never make your configuration unsavable." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ], "default": "medium", "description": "How hard the review works. Higher effort costs more and finds more." }, "severityFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "nit", "description": "The lowest severity that survives at all. Findings under this bar are recorded for the dashboard and never posted." }, "maxComments": { "type": "integer", "exclusiveMinimum": 0, "default": 30, "description": "The most inline comments a SINGLE run may post." }, "maxOpenCommentsPerPr": { "type": "integer", "exclusiveMinimum": 0, "default": 40, "description": "The most ultrareview inline comments that may be open on one pull request at a time, counted across every run. At the ceiling, a new run moves its lowest-severity findings into the summary instead of opening more threads. Blocking findings always stay inline." }, "inlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The lowest severity that earns its own inline comment. Anything below it is listed in full in the review summary instead: moved, never dropped." }, "incrementInlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The same bar again, applied only to follow-up pushes, so a second push does not re-carpet a pull request with small notes. The opening review is never affected." }, "verificationStrictness": { "type": "number", "enum": [ 0, 1, 2, 3 ], "default": 1, "description": "How many independent critics have to agree with a finding before it posts. Zero posts what the finders produced; three is the most adversarial." }, "maxVerifyCritics": { "type": "integer", "exclusiveMinimum": 0, "description": "A ceiling on critics per group of findings. Leave it unset unless you are deliberately capping cost." }, "verifyMode": { "type": "string", "enum": [ "panel", "screen-then-panel" ], "default": "panel", "description": "How verification is staged. `panel` sends every candidate straight to its own critics. `screen-then-panel` runs one pass over all the candidates first, which is the only place a cross-finding view exists, and kills duplicates and the immaterial before the critics ever see them." }, "remedyPolicy": { "type": "string", "enum": [ "off", "label", "strict" ], "default": "label", "description": "What happens to a suggested fix no critic could vouch for. `label` says so in the comment, `strict` also withholds the one-click apply, and `off` is the old behaviour that shows the suggestion with no caution." }, "maxOutputTokens": { "type": "integer", "minimum": 1000, "maximum": 128000, "description": "The output budget for each agent this profile runs. Unset means a generous default. Set it too small and an agent is truncated mid-answer, which quietly loses its whole dimension." }, "tone": { "type": "string", "enum": [ "terse", "balanced", "mentor" ], "default": "balanced", "description": "How the review talks." }, "rulePacks": { "type": "array", "items": { "type": "string" }, "description": "Names of the organization's rule packs to attach to this profile. The packs themselves live on the organization settings." }, "memoryScope": { "type": "string", "enum": [ "repo", "repo+path", "repo+author" ], "default": "repo", "description": "How widely this profile's learned memory applies: the whole repository, or narrowed to the path or the author it was learned from." }, "autofix": { "type": "boolean", "const": false, "default": false, "description": "Reserved. Always false in v1." } }, "required": [], "additionalProperties": false, "title": "ProfilePatch", "description": "The profile fields to change. Anything you leave out keeps its value. Sending `name` renames the profile." }, "ProfileWrite": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "What you call this profile. Repositories and routing rules refer to it by this name, matched without regard to case or surrounding whitespace." }, "description": { "type": "string", "description": "A sentence for whoever reads the profile list later. The review itself does not use it." }, "dimensions": { "type": "array", "items": { "type": "string", "enum": [ "correctness", "security", "performance", "api-contract", "style", "tests", "docs" ] }, "minItems": 1, "description": "What the review looks for. At least one is required, and each one is a separate pass over the change." }, "model": { "type": "string", "minLength": 1, "default": "claude-opus-4-8", "description": "Which model runs the review. A bare model id and a provider-qualified ref both work verbatim. Whether a ref actually resolves is a review-time question, not a save-time one, so a registry that has not caught up yet can never make your configuration unsavable." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ], "default": "medium", "description": "How hard the review works. Higher effort costs more and finds more." }, "severityFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "nit", "description": "The lowest severity that survives at all. Findings under this bar are recorded for the dashboard and never posted." }, "maxComments": { "type": "integer", "exclusiveMinimum": 0, "default": 30, "description": "The most inline comments a SINGLE run may post." }, "maxOpenCommentsPerPr": { "type": "integer", "exclusiveMinimum": 0, "default": 40, "description": "The most ultrareview inline comments that may be open on one pull request at a time, counted across every run. At the ceiling, a new run moves its lowest-severity findings into the summary instead of opening more threads. Blocking findings always stay inline." }, "inlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The lowest severity that earns its own inline comment. Anything below it is listed in full in the review summary instead: moved, never dropped." }, "incrementInlineFloor": { "type": "string", "enum": [ "critical", "major", "minor", "nit" ], "default": "major", "description": "The same bar again, applied only to follow-up pushes, so a second push does not re-carpet a pull request with small notes. The opening review is never affected." }, "verificationStrictness": { "type": "number", "enum": [ 0, 1, 2, 3 ], "default": 1, "description": "How many independent critics have to agree with a finding before it posts. Zero posts what the finders produced; three is the most adversarial." }, "maxVerifyCritics": { "type": "integer", "exclusiveMinimum": 0, "description": "A ceiling on critics per group of findings. Leave it unset unless you are deliberately capping cost." }, "verifyMode": { "type": "string", "enum": [ "panel", "screen-then-panel" ], "default": "panel", "description": "How verification is staged. `panel` sends every candidate straight to its own critics. `screen-then-panel` runs one pass over all the candidates first, which is the only place a cross-finding view exists, and kills duplicates and the immaterial before the critics ever see them." }, "remedyPolicy": { "type": "string", "enum": [ "off", "label", "strict" ], "default": "label", "description": "What happens to a suggested fix no critic could vouch for. `label` says so in the comment, `strict` also withholds the one-click apply, and `off` is the old behaviour that shows the suggestion with no caution." }, "maxOutputTokens": { "type": "integer", "minimum": 1000, "maximum": 128000, "description": "The output budget for each agent this profile runs. Unset means a generous default. Set it too small and an agent is truncated mid-answer, which quietly loses its whole dimension." }, "tone": { "type": "string", "enum": [ "terse", "balanced", "mentor" ], "default": "balanced", "description": "How the review talks." }, "rulePacks": { "type": "array", "items": { "type": "string" }, "description": "Names of the organization's rule packs to attach to this profile. The packs themselves live on the organization settings." }, "memoryScope": { "type": "string", "enum": [ "repo", "repo+path", "repo+author" ], "default": "repo", "description": "How widely this profile's learned memory applies: the whole repository, or narrowed to the path or the author it was learned from." }, "autofix": { "type": "boolean", "const": false, "default": false, "description": "Reserved. Always false in v1." }, "builtIn": { "type": "boolean", "description": "True for a profile that ships with ultrareview, false for one your organization authored." }, "dryRun": { "type": "boolean", "description": "True when nothing was written because you asked for a dry run." } }, "required": [ "name", "dimensions", "builtIn", "dryRun" ], "additionalProperties": false, "title": "ProfileWrite", "description": "The resource as it now stands, plus whether this was a dry run. The same shape a read of it returns." }, "ProfileList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileRead" }, "description": "The profiles on this page, in a stable order." }, "hasMore": { "type": "boolean", "description": "True when another page exists." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass this back as `cursor` to get the next page. Null on the last page. Opaque: read it, do not parse it." } }, "required": [ "data", "hasMore", "nextCursor" ] }, "ApplyProfileRequest": { "type": "object", "title": "ApplyProfileRequest", "properties": { "target": { "type": "string", "enum": [ "org-default", "repo" ], "description": "`org-default` makes it the organization default. `repo` pins it to one repository." }, "repo": { "type": "string", "description": "`owner/name`. Required when `target` is `repo`, ignored otherwise.", "example": "acme/storefront" } }, "required": [ "target" ], "additionalProperties": false }, "RepoSummary": { "type": "object", "title": "RepoSummary", "description": "A connected repository, with the two policy fields you are most likely to want in a list.", "properties": { "id": { "type": "string", "description": "GitHub's own repository id, as a string. Stable across renames, and the id the audit trail records." }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GitHub owner, as GitHub spells it. Null for a repository connected before ultrareview started recording coordinates." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GitHub repository name. Null for the same reason as `owner`." }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner/name`, which is how every endpoint addresses a repository. Null when the coordinates are unknown, and such a repository has to be reconnected before the API can address it." }, "autoReview": { "type": "string", "enum": [ "on", "off" ], "description": "Whether pull requests here are reviewed automatically." }, "profileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The profile this repository is pinned to, or null when it follows the organization default." }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The settings version, or null for a repository that has never been configured." } }, "required": [ "id", "owner", "name", "fullName", "autoReview", "profileName", "version" ] }, "RepoList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RepoSummary" }, "description": "The repositories on this page, in a stable order." }, "hasMore": { "type": "boolean", "description": "True when another page exists." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass this back as `cursor` to get the next page. Null on the last page. Opaque: read it, do not parse it." } }, "required": [ "data", "hasMore", "nextCursor" ] }, "Repo": { "type": "object", "title": "Repo", "properties": { "id": { "type": "string", "description": "GitHub's own repository id, as a string. Stable across renames, and the id the audit trail records." }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GitHub owner, as GitHub spells it. Null for a repository connected before ultrareview started recording coordinates." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GitHub repository name. Null for the same reason as `owner`." }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner/name`, which is how every endpoint addresses a repository. Null when the coordinates are unknown, and such a repository has to be reconnected before the API can address it." }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/RepoSettings" }, { "type": "null" } ], "description": "This repository's own settings, or null when it has never been configured and inherits everything." }, "effective": { "type": "object", "description": "What a review running right now would actually use, with every inherited and default value resolved.", "properties": { "profileName": { "type": "string", "description": "The profile that would run: this repository's pin if it has one, otherwise the organization default." }, "maxReviewFiles": { "type": "integer", "description": "The changed-file ceiling in force." }, "maxReviewDiffLines": { "type": "integer", "description": "The changed-line ceiling in force." } }, "required": [ "profileName", "maxReviewFiles", "maxReviewDiffLines" ] } }, "required": [ "id", "owner", "name", "fullName", "settings", "effective" ] }, "RepoWrite": { "type": "object", "title": "RepoWrite", "properties": { "id": { "type": "string", "description": "GitHub's own repository id, as a string. Stable across renames, and the id the audit trail records." }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GitHub owner, as GitHub spells it. Null for a repository connected before ultrareview started recording coordinates." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The GitHub repository name. Null for the same reason as `owner`." }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner/name`, which is how every endpoint addresses a repository. Null when the coordinates are unknown, and such a repository has to be reconnected before the API can address it." }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/RepoSettings" }, { "type": "null" } ], "description": "This repository's own settings, or null when it has never been configured and inherits everything." }, "effective": { "type": "object", "description": "What a review running right now would actually use, with every inherited and default value resolved.", "properties": { "profileName": { "type": "string", "description": "The profile that would run: this repository's pin if it has one, otherwise the organization default." }, "maxReviewFiles": { "type": "integer", "description": "The changed-file ceiling in force." }, "maxReviewDiffLines": { "type": "integer", "description": "The changed-line ceiling in force." } }, "required": [ "profileName", "maxReviewFiles", "maxReviewDiffLines" ] }, "dryRun": { "type": "boolean", "description": "True when nothing was written because you asked for a dry run." } }, "required": [ "id", "owner", "name", "fullName", "settings", "effective", "dryRun" ], "description": "The resource as it now stands, plus whether this was a dry run. The same shape a read of it returns." }, "RepoSettings": { "type": "object", "title": "RepoSettings", "description": "This repository's own review settings. Null means the value is not set here and is inherited from the organization or from the built-in default. A repository that has never been configured has no settings row at all, and this is null.", "properties": { "autoReview": { "type": "string", "enum": [ "on", "off" ], "description": "Whether pull requests in this repository are reviewed automatically." }, "reviewOnPush": { "type": [ "boolean", "null" ], "description": "Whether a push to an already-open pull request starts a fresh review." }, "profileName": { "type": [ "string", "null" ], "description": "The profile this repository uses, overriding the organization default. Null inherits." }, "reviewEffort": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, { "type": "null" } ], "description": "How hard the reviewer thinks on this repository, overriding the profile's own setting. Null uses each profile's effort." }, "routing": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "branches": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "titleMatches": { "type": "string", "minLength": 1 }, "minChangedFiles": { "type": "integer", "exclusiveMinimum": 0 }, "authors": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "additionalProperties": false }, "use": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "review", "skip" ] } }, "required": [ "when" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Send matching files to a different profile, or leave them out. Each rule says when it applies (paths, labels, branches, a title pattern, authors, a minimum change size) and either which profile to use, which must exist, or `action: \"skip\"` to exclude the matching files from review, which needs no profile; the first rule that matches a file wins. A repository's rules run before the organization's: for a file both match, the repository's rule wins; a file no repository rule matches falls through to the organization's rules, then to the default profile." }, "requireVerifiedSuggestions": { "type": [ "boolean", "null" ], "description": "This repository's answer to the organization's strict-suggestion setting. Null inherits." }, "maxReviewFiles": { "type": [ "number", "null" ], "description": "The largest pull request, counted in changed files, that still gets a review. Null uses the default." }, "maxReviewDiffLines": { "type": [ "number", "null" ], "description": "The largest pull request, counted in changed lines, that still gets a review. Null uses the default." }, "watchedPaths": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Narrow automatic review to pull requests that touch these paths. Null watches the whole repository." }, "workerTier": { "type": [ "boolean", "null" ], "description": "Whether this repository's automatic reviews may claim the review worker tier." }, "fixPullRequests": { "type": [ "boolean", "null" ], "description": "Whether ultrareview may open a pull request of its own when it is asked to fix something." }, "updatedBy": { "type": "string", "description": "Who wrote these settings last. An API write records the token id, not its editable label." }, "updatedAt": { "type": "integer", "description": "When these settings were last written, in milliseconds since the epoch." }, "version": { "type": "integer", "description": "Increments on every save. Send it back as `expectedVersion` to make your next write refuse rather than clobber a change you did not see." } }, "required": [ "autoReview", "reviewOnPush", "profileName", "reviewEffort", "routing", "requireVerifiedSuggestions", "maxReviewFiles", "maxReviewDiffLines", "watchedPaths", "workerTier", "fixPullRequests", "updatedBy", "updatedAt", "version" ] }, "RepoSettingsPatch": { "type": "object", "title": "RepoSettingsPatch", "description": "The settings to change. Leave a key out to keep its stored value, send null to clear it back to inherited or default, send a value to set it. Naming no key at all is refused, because it would be a write that means nothing.", "properties": { "autoReview": { "type": "string", "enum": [ "on", "off" ], "description": "Whether pull requests in this repository are reviewed automatically." }, "reviewOnPush": { "type": [ "boolean", "null" ], "description": "Whether a push to an already-open pull request starts a fresh review." }, "profileName": { "type": [ "string", "null" ], "description": "The profile this repository uses, overriding the organization default. Null inherits." }, "reviewEffort": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, { "type": "null" } ], "description": "How hard the reviewer thinks on this repository, overriding the profile's own setting. Null uses each profile's effort." }, "routing": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "branches": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "titleMatches": { "type": "string", "minLength": 1 }, "minChangedFiles": { "type": "integer", "exclusiveMinimum": 0 }, "authors": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "additionalProperties": false }, "use": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "review", "skip" ] } }, "required": [ "when" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Send matching files to a different profile, or leave them out. Each rule says when it applies (paths, labels, branches, a title pattern, authors, a minimum change size) and either which profile to use, which must exist, or `action: \"skip\"` to exclude the matching files from review, which needs no profile; the first rule that matches a file wins. A repository's rules run before the organization's: for a file both match, the repository's rule wins; a file no repository rule matches falls through to the organization's rules, then to the default profile." }, "requireVerifiedSuggestions": { "type": [ "boolean", "null" ], "description": "This repository's answer to the organization's strict-suggestion setting. Null inherits." }, "maxReviewFiles": { "type": [ "number", "null" ], "description": "The largest pull request, counted in changed files, that still gets a review. Null uses the default." }, "maxReviewDiffLines": { "type": [ "number", "null" ], "description": "The largest pull request, counted in changed lines, that still gets a review. Null uses the default." }, "watchedPaths": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Narrow automatic review to pull requests that touch these paths. Null watches the whole repository." }, "workerTier": { "type": [ "boolean", "null" ], "description": "Whether this repository's automatic reviews may claim the review worker tier." }, "fixPullRequests": { "type": [ "boolean", "null" ], "description": "Whether ultrareview may open a pull request of its own when it is asked to fix something." }, "expectedVersion": { "type": "integer", "description": "The `version` you read. The write is refused with `version_conflict` if anything changed in between. Optional, because a single write is atomic without it; multi-step agents should send it." } }, "additionalProperties": false, "minProperties": 1 }, "OrgSettings": { "type": "object", "properties": { "defaultProfile": { "type": "string", "default": "default", "description": "The profile every repository uses unless it is pinned to another one, or a routing rule sends a file somewhere else." }, "blockingPolicy": { "type": "string", "enum": [ "advisory", "blocking" ], "default": "advisory", "description": "Whether a review may hold a merge. `advisory`, the default, always posts as a comment and leaves the check green. `blocking` fails the check and requests changes on a critical or major finding, so a branch protection rule can hold the merge." }, "reviewScope": { "type": "string", "enum": [ "changes-only", "changes-plus-related" ], "default": "changes-only", "description": "What the posted review is allowed to talk about. `changes-only` sticks to lines the pull request added. `changes-plus-related` also shows observations about surrounding code, demoted into the summary." }, "requireVerifiedSuggestions": { "type": "boolean", "default": false, "description": "When true, only suggestions whose replacement text was checked against the real diff keep their one-click apply." }, "ignore": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [ "**/pnpm-lock.yaml", "**/package-lock.json", "**/yarn.lock", "**/bun.lock", "**/bun.lockb", "**/deno.lock", "**/Cargo.lock", "**/composer.lock", "**/Gemfile.lock", "**/poetry.lock", "**/uv.lock", "**/go.sum", "**/*.png", "**/*.jpg", "**/*.jpeg", "**/*.gif", "**/*.webp", "**/*.avif", "**/*.ico", "**/*.bmp", "**/*.mp4", "**/*.mov", "**/*.webm", "**/*.mp3", "**/*.wav", "**/*.ogg", "**/*.woff", "**/*.woff2", "**/*.ttf", "**/*.otf", "**/*.eot", "**/*.pdf", "**/*.zip", "**/*.gz", "**/*.tgz", "**/*.jar", "**/*.wasm", "**/*.min.js", "**/*.min.css", "**/*.js.map", "**/*.css.map" ], "description": "Glob patterns for changed files the review skips entirely: lockfiles, generated code, vendored dependencies, build output. `*` matches within a path segment and `**` across segments. The deterministic scanner still reads every file, so a secret committed into an ignored path is still reported." }, "routing": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Glob patterns for the changed file's path. `*` matches within a segment, `**` across segments." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Labels on the pull request." }, "branches": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Regular expressions matched against the head branch name." }, "titleMatches": { "type": "string", "minLength": 1, "description": "A regular expression matched against the pull request title." }, "minChangedFiles": { "type": "integer", "exclusiveMinimum": 0, "description": "Only apply this rule to pull requests at least this large." }, "authors": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "GitHub logins of the pull request author." } }, "additionalProperties": false, "description": "What a file has to look like for this rule to claim it. Every condition present must hold. An empty object matches everything." }, "use": { "type": "string", "minLength": 1, "description": "The profile that reviews matching files. Required on a review rule; ignored on a skip rule." }, "action": { "type": "string", "enum": [ "review", "skip" ], "description": "What a match does. Absent or `review` reviews the file with `use`. `skip` excludes it from the AI review, though the deterministic scanner still reads it, so a secret committed into a skipped path is still reported." } }, "required": [ "when" ], "additionalProperties": false }, "default": [], "description": "Rules that send matching files to a particular profile, or skip them. First match wins." }, "rulePacks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name a profile refers to this pack by." }, "instructions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The lines of extra instruction this pack contributes to any profile that attaches it." } }, "required": [ "name", "instructions" ], "additionalProperties": false }, "description": "Named blocks of extra instructions that a profile can attach by name." }, "memory": { "anyOf": [ { "type": "object", "properties": { "instructionFilesBudgetBytes": { "type": "integer", "minimum": 0, "description": "The total bytes of guidance a single review may read. Zero turns guidance ingestion off for this organization. Over-large values are clamped at use rather than refused, so a committed number can never invalidate the whole configuration." }, "instructionFilePerFileBytes": { "type": "integer", "minimum": 1000, "description": "The per-file cap, raised or lowered. Raising it lets a repository whose main CLAUDE.md sits over the default be read whole instead of truncated; the total budget above still bounds what a review injects." }, "instructionFilePatterns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 32, "description": "The recognized guidance filenames, REPLACING the built-in list rather than adding to it. `*` matches within one path segment; `**` is refused, because a custom pattern must not turn selection into a repository-wide walk." } }, "additionalProperties": false, "description": "Limits on the repository guidance files (CLAUDE.md, AGENTS.md and friends) that a review is allowed to read." }, { "type": "null" } ], "description": "Limits on the repository guidance files (CLAUDE.md, AGENTS.md and friends) that a review is allowed to read." }, "updatedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When these settings were last written, in milliseconds since the epoch. Null when the organization has never saved any." } }, "additionalProperties": false, "required": [ "defaultProfile", "blockingPolicy", "reviewScope", "requireVerifiedSuggestions", "ignore", "routing", "rulePacks", "memory", "updatedAt" ], "title": "OrgSettings", "description": "Everything about how this organization reviews, except the profiles themselves." }, "OrgSettingsPatch": { "type": "object", "properties": { "defaultProfile": { "type": "string", "default": "default", "description": "The profile every repository uses unless it is pinned to another one, or a routing rule sends a file somewhere else." }, "blockingPolicy": { "type": "string", "enum": [ "advisory", "blocking" ], "default": "advisory", "description": "Whether a review may hold a merge. `advisory`, the default, always posts as a comment and leaves the check green. `blocking` fails the check and requests changes on a critical or major finding, so a branch protection rule can hold the merge." }, "reviewScope": { "type": "string", "enum": [ "changes-only", "changes-plus-related" ], "default": "changes-only", "description": "What the posted review is allowed to talk about. `changes-only` sticks to lines the pull request added. `changes-plus-related` also shows observations about surrounding code, demoted into the summary." }, "requireVerifiedSuggestions": { "type": "boolean", "default": false, "description": "When true, only suggestions whose replacement text was checked against the real diff keep their one-click apply." }, "ignore": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [ "**/pnpm-lock.yaml", "**/package-lock.json", "**/yarn.lock", "**/bun.lock", "**/bun.lockb", "**/deno.lock", "**/Cargo.lock", "**/composer.lock", "**/Gemfile.lock", "**/poetry.lock", "**/uv.lock", "**/go.sum", "**/*.png", "**/*.jpg", "**/*.jpeg", "**/*.gif", "**/*.webp", "**/*.avif", "**/*.ico", "**/*.bmp", "**/*.mp4", "**/*.mov", "**/*.webm", "**/*.mp3", "**/*.wav", "**/*.ogg", "**/*.woff", "**/*.woff2", "**/*.ttf", "**/*.otf", "**/*.eot", "**/*.pdf", "**/*.zip", "**/*.gz", "**/*.tgz", "**/*.jar", "**/*.wasm", "**/*.min.js", "**/*.min.css", "**/*.js.map", "**/*.css.map" ], "description": "Glob patterns for changed files the review skips entirely: lockfiles, generated code, vendored dependencies, build output. `*` matches within a path segment and `**` across segments. The deterministic scanner still reads every file, so a secret committed into an ignored path is still reported." }, "routing": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Glob patterns for the changed file's path. `*` matches within a segment, `**` across segments." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Labels on the pull request." }, "branches": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Regular expressions matched against the head branch name." }, "titleMatches": { "type": "string", "minLength": 1, "description": "A regular expression matched against the pull request title." }, "minChangedFiles": { "type": "integer", "exclusiveMinimum": 0, "description": "Only apply this rule to pull requests at least this large." }, "authors": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "GitHub logins of the pull request author." } }, "additionalProperties": false, "description": "What a file has to look like for this rule to claim it. Every condition present must hold. An empty object matches everything." }, "use": { "type": "string", "minLength": 1, "description": "The profile that reviews matching files. Required on a review rule; ignored on a skip rule." }, "action": { "type": "string", "enum": [ "review", "skip" ], "description": "What a match does. Absent or `review` reviews the file with `use`. `skip` excludes it from the AI review, though the deterministic scanner still reads it, so a secret committed into a skipped path is still reported." } }, "required": [ "when" ], "additionalProperties": false }, "default": [], "description": "Rules that send matching files to a particular profile, or skip them. First match wins." }, "rulePacks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name a profile refers to this pack by." }, "instructions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The lines of extra instruction this pack contributes to any profile that attaches it." } }, "required": [ "name", "instructions" ], "additionalProperties": false }, "description": "Named blocks of extra instructions that a profile can attach by name." }, "memory": { "type": "object", "properties": { "instructionFilesBudgetBytes": { "type": "integer", "minimum": 0, "description": "The total bytes of guidance a single review may read. Zero turns guidance ingestion off for this organization. Over-large values are clamped at use rather than refused, so a committed number can never invalidate the whole configuration." }, "instructionFilePerFileBytes": { "type": "integer", "minimum": 1000, "description": "The per-file cap, raised or lowered. Raising it lets a repository whose main CLAUDE.md sits over the default be read whole instead of truncated; the total budget above still bounds what a review injects." }, "instructionFilePatterns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 32, "description": "The recognized guidance filenames, REPLACING the built-in list rather than adding to it. `*` matches within one path segment; `**` is refused, because a custom pattern must not turn selection into a repository-wide walk." } }, "additionalProperties": false, "description": "Limits on the repository guidance files (CLAUDE.md, AGENTS.md and friends) that a review is allowed to read." } }, "additionalProperties": false, "title": "OrgSettingsPatch", "description": "The slices to replace. A key you name is replaced whole (arrays are not merged element by element), and a key you leave out is untouched. Profiles are managed through the profile endpoints, so `profiles` is refused here." }, "OrgSettingsWrite": { "type": "object", "properties": { "defaultProfile": { "type": "string", "default": "default", "description": "The profile every repository uses unless it is pinned to another one, or a routing rule sends a file somewhere else." }, "blockingPolicy": { "type": "string", "enum": [ "advisory", "blocking" ], "default": "advisory", "description": "Whether a review may hold a merge. `advisory`, the default, always posts as a comment and leaves the check green. `blocking` fails the check and requests changes on a critical or major finding, so a branch protection rule can hold the merge." }, "reviewScope": { "type": "string", "enum": [ "changes-only", "changes-plus-related" ], "default": "changes-only", "description": "What the posted review is allowed to talk about. `changes-only` sticks to lines the pull request added. `changes-plus-related` also shows observations about surrounding code, demoted into the summary." }, "requireVerifiedSuggestions": { "type": "boolean", "default": false, "description": "When true, only suggestions whose replacement text was checked against the real diff keep their one-click apply." }, "ignore": { "type": "array", "items": { "type": "string", "minLength": 1 }, "default": [ "**/pnpm-lock.yaml", "**/package-lock.json", "**/yarn.lock", "**/bun.lock", "**/bun.lockb", "**/deno.lock", "**/Cargo.lock", "**/composer.lock", "**/Gemfile.lock", "**/poetry.lock", "**/uv.lock", "**/go.sum", "**/*.png", "**/*.jpg", "**/*.jpeg", "**/*.gif", "**/*.webp", "**/*.avif", "**/*.ico", "**/*.bmp", "**/*.mp4", "**/*.mov", "**/*.webm", "**/*.mp3", "**/*.wav", "**/*.ogg", "**/*.woff", "**/*.woff2", "**/*.ttf", "**/*.otf", "**/*.eot", "**/*.pdf", "**/*.zip", "**/*.gz", "**/*.tgz", "**/*.jar", "**/*.wasm", "**/*.min.js", "**/*.min.css", "**/*.js.map", "**/*.css.map" ], "description": "Glob patterns for changed files the review skips entirely: lockfiles, generated code, vendored dependencies, build output. `*` matches within a path segment and `**` across segments. The deterministic scanner still reads every file, so a secret committed into an ignored path is still reported." }, "routing": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Glob patterns for the changed file's path. `*` matches within a segment, `**` across segments." }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Labels on the pull request." }, "branches": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Regular expressions matched against the head branch name." }, "titleMatches": { "type": "string", "minLength": 1, "description": "A regular expression matched against the pull request title." }, "minChangedFiles": { "type": "integer", "exclusiveMinimum": 0, "description": "Only apply this rule to pull requests at least this large." }, "authors": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "GitHub logins of the pull request author." } }, "additionalProperties": false, "description": "What a file has to look like for this rule to claim it. Every condition present must hold. An empty object matches everything." }, "use": { "type": "string", "minLength": 1, "description": "The profile that reviews matching files. Required on a review rule; ignored on a skip rule." }, "action": { "type": "string", "enum": [ "review", "skip" ], "description": "What a match does. Absent or `review` reviews the file with `use`. `skip` excludes it from the AI review, though the deterministic scanner still reads it, so a secret committed into a skipped path is still reported." } }, "required": [ "when" ], "additionalProperties": false }, "default": [], "description": "Rules that send matching files to a particular profile, or skip them. First match wins." }, "rulePacks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name a profile refers to this pack by." }, "instructions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The lines of extra instruction this pack contributes to any profile that attaches it." } }, "required": [ "name", "instructions" ], "additionalProperties": false }, "description": "Named blocks of extra instructions that a profile can attach by name." }, "memory": { "anyOf": [ { "type": "object", "properties": { "instructionFilesBudgetBytes": { "type": "integer", "minimum": 0, "description": "The total bytes of guidance a single review may read. Zero turns guidance ingestion off for this organization. Over-large values are clamped at use rather than refused, so a committed number can never invalidate the whole configuration." }, "instructionFilePerFileBytes": { "type": "integer", "minimum": 1000, "description": "The per-file cap, raised or lowered. Raising it lets a repository whose main CLAUDE.md sits over the default be read whole instead of truncated; the total budget above still bounds what a review injects." }, "instructionFilePatterns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 32, "description": "The recognized guidance filenames, REPLACING the built-in list rather than adding to it. `*` matches within one path segment; `**` is refused, because a custom pattern must not turn selection into a repository-wide walk." } }, "additionalProperties": false, "description": "Limits on the repository guidance files (CLAUDE.md, AGENTS.md and friends) that a review is allowed to read." }, { "type": "null" } ], "description": "Limits on the repository guidance files (CLAUDE.md, AGENTS.md and friends) that a review is allowed to read." }, "updatedAt": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "When these settings were last written, in milliseconds since the epoch. Null when the organization has never saved any." }, "dryRun": { "type": "boolean", "description": "True when nothing was written because you asked for a dry run." } }, "additionalProperties": false, "required": [ "defaultProfile", "blockingPolicy", "reviewScope", "requireVerifiedSuggestions", "ignore", "routing", "rulePacks", "memory", "updatedAt", "dryRun" ], "title": "OrgSettingsWrite", "description": "The resource as it now stands, plus whether this was a dry run. The same shape a read of it returns." } }, "responses": { "Unauthorized": { "description": "No usable token. The `WWW-Authenticate` header names which of the four cases it was.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "token_missing", "message": "Send an API token: \"Authorization: Bearer urk_...\". An org admin can mint one in the dashboard, under Configuration and then API tokens.", "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "Forbidden": { "description": "The token is valid but was not minted with the scope this endpoint needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "This endpoint requires the profiles:write scope.", "details": { "requiredScope": "profiles:write", "tokenScopes": [ "profiles:read" ] }, "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "NotFound": { "description": "No such profile, repository, or path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No profile named \"strict-security\" exists in this organization. List profiles with GET /v1/profiles.", "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "Conflict": { "description": "The current state prevents this. Branch on `error.code`, not the status: `conflict` (the name is taken, or something still points at what you tried to remove), `version_conflict` (the settings changed since you read them), `builtin_profile` (built-ins cannot be edited or deleted in place), `org_config_unreadable` (the stored organization config will not parse; fix it in the dashboard first).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "alreadyExists": { "summary": "Something with that name is already there", "value": { "error": { "code": "conflict", "message": "A profile named \"strict-security\" already exists. Use PATCH /v1/profiles/strict-security to change it.", "docs": "https://mobsession.ai/docs/api-tokens" } } }, "stillReferenced": { "summary": "Something still points at what you tried to remove", "value": { "error": { "code": "conflict", "message": "Can't save: profile \"strict-security\" is still pinned to repository 574128390. Change that repository's profile first.", "docs": "https://mobsession.ai/docs/api-tokens" } } }, "versionConflict": { "summary": "It changed since you read it", "value": { "error": { "code": "version_conflict", "message": "This repository's settings changed since you read them. Fetch the current settings, then re-apply your change.", "docs": "https://mobsession.ai/docs/api-tokens" } } }, "builtinProfile": { "summary": "Built-ins are not editable in place", "value": { "error": { "code": "builtin_profile", "message": "\"security\" is a built-in profile and can't be edited directly. Create an org profile with the same name to shadow it.", "docs": "https://mobsession.ai/docs/api-tokens" } } }, "configUnreadable": { "summary": "The stored configuration will not parse", "value": { "error": { "code": "org_config_unreadable", "message": "This organization's stored review configuration can't be read. Fix it on the Configuration page first.", "docs": "https://mobsession.ai/docs/api-tokens" } } } } } } }, "BadRequest": { "description": "The request could not be read at all: unparseable JSON, or a query parameter this endpoint does not accept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "malformed_json", "message": "The body is not valid JSON.", "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "UnsupportedMediaType": { "description": "A body was sent without a JSON content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Send the body as application/json. Add: -H \"content-type: application/json\".", "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "PayloadTooLarge": { "description": "The body is larger than the API reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "The body exceeds 524288 bytes.", "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "ValidationFailed": { "description": "The body parsed, but its content is not acceptable. The message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "\"maxReviewFiles\" must be a number, or null to clear.", "details": { "key": "maxReviewFiles" }, "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "RateLimited": { "description": "Over the per-token ceiling of 120 requests or 30 writes a minute. `Retry-After` carries the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "This token hit its rate limit. Slow down and retry.", "details": { "retryAfterMs": 21000 }, "docs": "https://mobsession.ai/docs/api-tokens" } } } } }, "ServerError": { "description": "Something broke on our side. `requestId` is logged with the failure; quote it to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side. If this persists, contact support and quote the request id.", "docs": "https://mobsession.ai/docs/api-tokens" } } } } } } } }