{ "openapi": "3.1.0", "info": { "title": "Diffinery REST API", "version": "0.1.0", "description": "The Diffinery REST API, generated from the server's router. Paths and payloads follow GitHub's REST API v3 where Diffinery has the same feature. Guide: https://diffinery.com/docs/reference/rest-api" }, "externalDocs": { "description": "Diffinery docs", "url": "https://diffinery.com/docs" }, "servers": [ { "url": "https://diffinery.com/api/v3" } ], "security": [ { "token": [] } ], "tags": [ { "name": "Meta" }, { "name": "Users" }, { "name": "Organizations" }, { "name": "Search" }, { "name": "Repositories" }, { "name": "Contents" }, { "name": "Releases" }, { "name": "Git database" }, { "name": "Branches and tags" }, { "name": "Commit statuses" }, { "name": "Checks" }, { "name": "Commits" }, { "name": "Branch protection" }, { "name": "Issues" }, { "name": "Pull requests" }, { "name": "Merge queue" }, { "name": "Deployments" }, { "name": "Environments" }, { "name": "Actions secrets and variables" }, { "name": "Actions artifacts and caches" }, { "name": "Actions" }, { "name": "Webhooks" }, { "name": "Packages" }, { "name": "Imports" }, { "name": "Status page" }, { "name": "Notifications and email" }, { "name": "Tokens and agents" }, { "name": "Sandboxes" }, { "name": "Other" } ], "paths": { "/": { "get": { "operationId": "get", "summary": "API root", "description": "Names the API and links to these docs and the MCP endpoint.\n\nAccess: No authentication needed.", "tags": [ "Meta" ], "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meta": { "get": { "operationId": "getMeta", "summary": "Instance metadata", "description": "Whether this instance issues OIDC tokens to workflows, and the runner image its last deploy set (`runner_image`; each job reports the image it ran on as `runner.image`), and whether it tells search engines about changed public pages through IndexNow (`indexnow`: `enabled`, `key_location` and the time, URL count, IndexNow status and `endpoint` of the `last_submission`; see [Site administration](/docs/admin/site-administration#search-engines)).\n\nAccess: No authentication needed.", "tags": [ "Meta" ], "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rate_limit": { "get": { "operationId": "getRateLimit", "summary": "Get rate limit status", "description": "For GitHub clients that check their budget before calling. It always reports a full, constant budget (15000 core requests an hour). Diffinery's real limits are per minute (2,000 requests per account, 60 new repositories, issues, pull requests, comments and the like, 300 requests per IP address without signing in) and answer 429 with `retry-after: 60`; see /docs/reference/rest-api#rate-limits.\n\nAccess: No authentication needed.", "tags": [ "Meta" ], "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user": { "get": { "operationId": "getUser", "summary": "Get the authenticated account", "description": "Returns your account, including `email` and `site_admin`. Agents get their own account (type `Bot`).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Users" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/avatar": { "put": { "operationId": "putUserAvatar", "summary": "Set your profile picture", "description": "Diffinery only. The raw request body is the image (JPEG, PNG or WebP, at most 5 MB), not JSON. Returns the new `avatar_url`. A token needs `write` or `admin` scope and must not be limited to repositories. Audited.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Users" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUserAvatar", "summary": "Remove your profile picture", "description": "Diffinery only. Goes back to generated initials and returns the `avatar_url`. Same token rules as setting one. Audited.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Users" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/orgs": { "get": { "operationId": "getUserOrgs", "summary": "List your organizations", "description": "Each organization carries your `role` in it (member, admin or owner).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Users" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postUserOrgs", "summary": "Create an organization", "description": "Access: Any active account (a token, or a browser session). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "description": "Organization login (letters, digits, `-` and `_`; no dots)." }, "name": { "type": "string", "description": "Display name (default: the login)." } }, "required": [ "login" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{login}": { "get": { "operationId": "getUsersByLogin", "summary": "Get an account", "description": "A user, organization or agent by login. A suspended person is `404` except to site administrators, who also see `suspended_at` and `suspension_reason`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Users" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invitations": { "get": { "operationId": "getInvitations", "summary": "List pending invitations to this instance", "description": "Site-wide invites only, not those to an organization or repository. Site admins only.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Organizations" ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postInvitations", "summary": "Invite someone to this instance", "description": "A site-wide invite with no organization. Site admins only.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Organizations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to invite." } }, "required": [ "email" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invitations/{id}": { "delete": { "operationId": "deleteInvitationsById", "summary": "Revoke an invitation to this instance", "description": "Site admins only. 404 when no pending site-wide invitation has this id. Audited.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}": { "get": { "operationId": "getOrgsByOrg", "summary": "Get an organization", "description": "GitHub's organization object. Members, the organization's agents, agents of members, and site admins also get `default_repository_permission`, the organization's base permission (`none`, `read`, `write` or `admin`).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchOrgsByOrg", "summary": "Update an organization", "description": "Organization owners (and site admins) only; admins and members get 403. Returns the updated organization. Every field is checked before anything is saved, so a bad value (422) changes nothing. Changing the base permission applies to every member right away; owners and admins always keep admin. Audited.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_repository_permission": { "type": "string", "description": "Base permission every member gets on the organization's repositories: `none`, `read` (the default for new organizations), `write` or `admin`." }, "name": { "type": "string", "description": "Display name. An empty value clears it, and pages show the login instead." } }, "required": [] } } } }, "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrg", "summary": "Delete an organization", "description": "Owners only (or site admins). Refused with 422 while the organization still owns repositories (transfer or delete them first), container images, or an import in progress. Its members, pending invitations, secrets and variables are removed, its agents disabled and their tokens revoked, and its login freed. Repositories transferred out of it keep redirecting from their old URLs. Audited. From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL (see /docs/security/overview#confirming-its-you).\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/avatar": { "put": { "operationId": "putOrgsByOrgAvatar", "summary": "Set an organization's picture", "description": "Diffinery only. Organization owners (and site admins) only. The raw request body is the image (JPEG, PNG or WebP, at most 5 MB), not JSON. Returns the new `avatar_url`. A token needs `write` or `admin` scope and must not be limited to repositories. Audited.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `write` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrgAvatar", "summary": "Remove an organization's picture", "description": "Diffinery only. Organization owners (and site admins) only. Goes back to generated initials and returns the `avatar_url`. Audited.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `write` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/invitations": { "get": { "operationId": "getOrgsByOrgInvitations", "summary": "List an organization's pending invitations", "description": "Owners and admins (or site admins). Each has an `id` to revoke it with.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `read` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postOrgsByOrgInvitations", "summary": "Invite someone to an organization", "description": "Emails an invite link. The response holds the link too, so you can share it yourself. Refused with 422 when the address already has a pending invitation to the organization (letter case doesn't matter) or belongs to a member. You can send at most 50 invitations in 24 hours (site admins aren't limited); more answer 429 `you can send at most 50 invitations in 24 hours; try again later`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to invite." }, "role": { "type": "string", "description": "`member` (default), `admin` or `owner`." } }, "required": [ "email" ] } } } }, "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/invitations/{id}": { "delete": { "operationId": "deleteOrgsByOrgInvitationsById", "summary": "Revoke an organization invitation", "description": "The link stops working and the address can be invited again. 404 when no pending invitation has this id. Audited.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/members": { "get": { "operationId": "getOrgsByOrgMembers", "summary": "List organization members", "description": "Members only (or site admins). Each entry carries the member's `role`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Organizations" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search/issues": { "get": { "operationId": "getSearchIssues", "summary": "Search issues and pull requests", "description": "Searches the repositories you can read (only public ones without a token), at most 50 per query; `incomplete_results` is true when more were left out. Qualifiers: `repo:`, `user:`, `org:`, `owner:`, `is:`, `type:`, `state:`, `draft:`, `label:`, `no:`, `author:`, `assignee:`, `head:`, `base:`, `in:`, `created:`, `updated:`, `closed:` and `sort:`; others are searched as text. Only the first 1000 results are available, and every `score` is 1.\n\nAccess: No authentication needed.", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query, at most 256 characters.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created` (default), `updated` or `comments`.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "`desc` (default) or `asc`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search/repositories": { "get": { "operationId": "getSearchRepositories", "summary": "Search repositories", "description": "Matches names, descriptions and topics of the repositories you can see (only public ones without a token). Qualifiers: `user:`, `org:`, `owner:`, `repo:`, `topic:`, `is:public`, `is:private`, `archived:` and `in:name,description,topics`. `fork:`, `language:`, `stars:`, `forks:`, `size:`, `pushed:` and `created:` are accepted but don't filter anything. Every `score` is 1.\n\nAccess: No authentication needed.", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query, at most 256 characters.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`updated` sorts by last push; anything else keeps the default order.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "With `sort=updated`: `desc` (default) or `asc`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/repos": { "get": { "operationId": "getOrgsByOrgRepos", "summary": "List an organization's repositories", "description": "Only the ones you can see. A token limited to repositories lists only those repositories.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postOrgsByOrgRepos", "summary": "Create an organization repository", "description": "Access: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Repositories" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Repository name." }, "description": { "type": "string", "description": "Short description." }, "visibility": { "type": "string", "description": "`private` (default) or `public`." }, "default_branch": { "type": "string", "description": "Default branch name (default `main`)." } }, "required": [ "name" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}": { "get": { "operationId": "getReposByOwnerByRepo", "summary": "Get a repository", "description": "Includes your role (`permissions.role`) and repository statistics.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepo", "summary": "Update a repository", "description": "Works on an archived repository too, so an admin can unarchive it with `archived: false`. Audited as `repo.update`, `repo.archive` or `repo.unarchive`. A new `name` renames the repository: its old name keeps redirecting (see the transfer endpoint), until a repository is created there again. 422 when the owner already has a repository with that name.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." }, "description": { "type": "string", "description": "New description." }, "visibility": { "type": "string", "description": "`private` or `public`." }, "default_branch": { "type": "string", "description": "New default branch (must exist)." }, "archived": { "type": "boolean", "description": "Archive (read-only) or unarchive." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepo", "summary": "Delete a repository", "description": "People only; agents can't delete repositories. Works on an archived repository too. Audited. From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL (see /docs/security/overview#confirming-its-you).\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/assignees": { "get": { "operationId": "getReposByOwnerByRepoAssignees", "summary": "List assignable people", "description": "Collaborators with triage access or more, plus the owner when the owner is a user.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/assignees/{login}": { "get": { "operationId": "getReposByOwnerByRepoAssigneesByLogin", "summary": "Check if someone can be assigned", "description": "204 when `login` is the repository's owner or a collaborator with triage access or more, 404 otherwise.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/collaborators": { "get": { "operationId": "getReposByOwnerByRepoCollaborators", "summary": "List collaborators", "description": "Each entry carries `role_name`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/collaborators/{login}": { "put": { "operationId": "putReposByOwnerByRepoCollaboratorsByLogin", "summary": "Invite a collaborator, or change one's role", "description": "As on GitHub, a person without access gets an invitation and has access once they accept it: the answer is `201` with the invitation (`id`, `repository`, `invitee`, `inviter`, `permissions`, `expires_at`), audited as `repo.invite`; asking again while it's pending changes its role. Agents, existing collaborators, members of the owning organization and yourself get the role at once: `204`, audited as `repo.collaborator.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "permission": { "type": "string", "description": "`read`, `triage`, `write` (default), `maintain` or `admin`; GitHub's `pull` and `push` work too." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoCollaboratorsByLogin", "summary": "Remove a collaborator", "description": "Audited as `repo.collaborator.remove`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/dispatches": { "post": { "operationId": "postReposByOwnerByRepoDispatches", "summary": "Trigger a repository_dispatch event", "description": "Starts workflows on the default branch that run `on: repository_dispatch` with this type, and sends the `repository_dispatch` webhook. Fails with 422 on an empty repository, and with 429 when the repository already has 500 unfinished workflow runs.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "Event type, at most 100 characters." }, "client_payload": { "type": "object", "description": "Data for workflows as `github.event.client_payload`: at most 10 top-level keys and 64 KB." } }, "required": [ "event_type" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/invitations": { "get": { "operationId": "getReposByOwnerByRepoInvitations", "summary": "List pending repository invitations", "description": "Invitations sent by email to people without an account. Each has an `id` to revoke it with.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/invitations/{id}": { "delete": { "operationId": "deleteReposByOwnerByRepoInvitationsById", "summary": "Revoke a repository invitation", "description": "The link stops working and the address can be invited again. 404 when no pending invitation to this repository has this id. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/languages": { "get": { "operationId": "getReposByOwnerByRepoLanguages", "summary": "List languages", "description": "Bytes of code per language on the default branch, largest first. Languages come from file extensions and a few well-known file names; vendored directories like `node_modules` and `vendor` are skipped.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/topics": { "get": { "operationId": "getReposByOwnerByRepoTopics", "summary": "Get topics", "description": "Returns `{ names }`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoTopics", "summary": "Replace topics", "description": "Names are lower-cased and deduplicated. Each starts with a letter or digit and has at most 50 letters, digits and dashes; at most 20 topics. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Every topic the repository should have (`[]` clears them)." } }, "required": [ "names" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/repos": { "get": { "operationId": "getUserRepos", "summary": "List repositories you can access", "description": "A token limited to repositories lists only those repositories.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Repositories" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postUserRepos", "summary": "Create a repository for yourself", "description": "An agent's repositories belong to its owner.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Repositories" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Repository name." }, "description": { "type": "string", "description": "Short description." }, "visibility": { "type": "string", "description": "`private` (default) or `public`." }, "default_branch": { "type": "string", "description": "Default branch name (default `main`)." } }, "required": [ "name" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{login}/repos": { "get": { "operationId": "getUsersByLoginRepos", "summary": "List an account's repositories", "description": "Only the ones you can see. A token limited to repositories lists only those repositories.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Repositories" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/contents": { "get": { "operationId": "getReposByOwnerByRepoContents", "summary": "List the root directory", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Branch, tag or commit (default: the default branch).", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/contents/{path}": { "get": { "operationId": "getReposByOwnerByRepoContentsByPath", "summary": "Get a file or directory", "description": "A directory returns an array of entries; a file returns its content base64-encoded.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Branch, tag or commit (default: the default branch).", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoContentsByPath", "summary": "Create or update a file", "description": "Commits one file.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Commit message." }, "content": { "type": "string", "description": "New content, base64-encoded." }, "branch": { "type": "string", "description": "Branch to commit to (default: the default branch)." } }, "required": [ "message", "content" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoContentsByPath", "summary": "Delete a file", "description": "Access: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Commit message." }, "branch": { "type": "string", "description": "Branch to commit to (default: the default branch)." } }, "required": [ "message" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/commits": { "post": { "operationId": "postReposByOwnerByRepoDiffineryCommits", "summary": "Commit several files at once", "description": "Diffinery only. Writes and deletes any number of files in one commit, without a git client. Pass `expected_head_sha` to fail instead of racing another writer. Push protection scans the new content as it does for `git push`: content that looks like a credential is refused with 422 and audited as `api.blocked_secret`. A repository admin who is a person can commit it anyway with an `allow_secrets` reason, audited as `api.secret_bypassed` and emailed to the repository's admins.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "type": "string", "description": "Branch to commit to." }, "message": { "type": "string", "description": "Commit message." }, "files": { "type": "array", "description": "Changes: `{ path, content, encoding: \"utf-8\" | \"base64\", mode: \"100644\" | \"100755\" }` or `{ path, delete: true }`." }, "base": { "type": "string", "description": "Create `branch` from this ref when it doesn't exist." }, "expected_head_sha": { "type": "string", "description": "Fail with 409 if the branch has moved." }, "allow_secrets": { "type": "string", "description": "Why a detected secret may be committed anyway (repository admins who are people; at most 200 characters are kept)." } }, "required": [ "branch", "message", "files" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/raw/{ref}/{path}": { "get": { "operationId": "getReposByOwnerByRepoRawByRefByPath", "summary": "Download a raw file", "description": "The file's bytes, served as text or `application/octet-stream`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/readme": { "get": { "operationId": "getReposByOwnerByRepoReadme", "summary": "Get the README", "description": "The README in the root directory, base64-encoded like a file from the contents API. A Markdown README wins when there are several. Send `Accept: application/vnd.github.raw` for the raw bytes.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Branch, tag or commit (default: the default branch).", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/readme/{dir}": { "get": { "operationId": "getReposByOwnerByRepoReadmeByDir", "summary": "Get a directory's README", "description": "Like the root README, for the directory `dir`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "dir", "in": "path", "required": true, "description": "dir", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Branch, tag or commit (default: the default branch).", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/tarball": { "get": { "operationId": "getReposByOwnerByRepoTarball", "summary": "Download a tarball", "description": "A `.tar.gz` of the repository's files, served directly (GitHub redirects to a download host instead). Built once per commit, at most 20 new builds per repository per hour (429 after that); repositories with more than 24 MB of files can't be archived (413). Uses the default branch.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/tarball/{ref}": { "get": { "operationId": "getReposByOwnerByRepoTarballByRef", "summary": "Download a tarball of a ref", "description": "A `.tar.gz` of the repository's files, served directly (GitHub redirects to a download host instead). Built once per commit, at most 20 new builds per repository per hour (429 after that); repositories with more than 24 MB of files can't be archived (413).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/zipball": { "get": { "operationId": "getReposByOwnerByRepoZipball", "summary": "Download a zip archive", "description": "A `.zip` (at most 65535 files) of the repository's files, served directly (GitHub redirects to a download host instead). Built once per commit, at most 20 new builds per repository per hour (429 after that); repositories with more than 24 MB of files can't be archived (413). Uses the default branch.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/zipball/{ref}": { "get": { "operationId": "getReposByOwnerByRepoZipballByRef", "summary": "Download a zip archive of a ref", "description": "A `.zip` (at most 65535 files) of the repository's files, served directly (GitHub redirects to a download host instead). Built once per commit, at most 20 new builds per repository per hour (429 after that); repositories with more than 24 MB of files can't be archived (413).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Contents" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases": { "get": { "operationId": "getReposByOwnerByRepoReleases", "summary": "List releases", "description": "Newest first. Drafts are included only for people with write access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoReleases", "summary": "Create a release", "description": "A published release (not a draft) creates its tag at `target_commitish` when the tag doesn't exist, sends `release` webhooks and starts `on: release` workflows; a draft only sends the `created` webhook. 422 when the tag already has a published release. Upload assets to the release's `upload_url`. `discussion_category_name` is ignored. See [Releases](/docs/collaboration/releases).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_name": { "type": "string", "description": "Tag to release." }, "target_commitish": { "type": "string", "description": "Branch, tag or commit for a new tag (default: the default branch)." }, "name": { "type": "string", "description": "Release title." }, "body": { "type": "string", "description": "Markdown notes, at most 125000 characters." }, "draft": { "type": "boolean", "description": "Save as a draft." }, "prerelease": { "type": "boolean", "description": "Mark as a prerelease." }, "make_latest": { "type": "string", "description": "`true` (default), `false`, or `legacy` (the newest by date)." }, "generate_release_notes": { "type": "boolean", "description": "Append generated notes to `body`." } }, "required": [ "tag_name" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/{id}": { "get": { "operationId": "getReposByOwnerByRepoReleasesById", "summary": "Get a release", "description": "Drafts are 404 for people without write access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoReleasesById", "summary": "Update a release", "description": "Send only what changes. Setting `draft` to false publishes the release (creating its tag if needed); setting it back to true unpublishes it. Sends `release` webhooks.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_name": { "type": "string", "description": "New tag." }, "target_commitish": { "type": "string", "description": "Branch, tag or commit for a new tag." }, "name": { "type": "string", "description": "Release title." }, "body": { "type": "string", "description": "Markdown notes, at most 125000 characters." }, "draft": { "type": "boolean", "description": "Draft or published." }, "prerelease": { "type": "boolean", "description": "Mark as a prerelease." }, "make_latest": { "type": "string", "description": "`true`, `false` or `legacy`." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoReleasesById", "summary": "Delete a release", "description": "Deletes its assets too; the tag stays. Sends the `release` webhook.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/{id}/assets": { "get": { "operationId": "getReposByOwnerByRepoReleasesByIdAssets", "summary": "List release assets", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/{id}/reactions": { "get": { "operationId": "getReposByOwnerByRepoReleasesByIdReactions", "summary": "List reactions to a release", "description": "Drafts are hidden from people without write access, and so are their reactions.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "content", "in": "query", "required": false, "description": "Only reactions with this content.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoReleasesByIdReactions", "summary": "Add a reaction to a release", "description": "Needs a signed-in account. Returns 201 for a new reaction, or 200 with the existing one when you had already reacted with that content.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket` or `eyes`." } }, "required": [ "content" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/{id}/reactions/{reaction}": { "delete": { "operationId": "deleteReposByOwnerByRepoReleasesByIdReactionsByReaction", "summary": "Delete a reaction from a release", "description": "Your own reactions, or anyone's with admin access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "reaction", "in": "path", "required": true, "description": "reaction", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/assets/{id}": { "get": { "operationId": "getReposByOwnerByRepoReleasesAssetsById", "summary": "Get a release asset", "description": "The asset's metadata, or the file itself with `Accept: application/octet-stream`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoReleasesAssetsById", "summary": "Update a release asset", "description": "`state` is accepted and ignored.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New file name (unique within the release)." }, "label": { "type": "string", "description": "Display label." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoReleasesAssetsById", "summary": "Delete a release asset", "description": "Access: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/generate-notes": { "post": { "operationId": "postReposByOwnerByRepoReleasesGenerateNotes", "summary": "Generate release notes", "description": "Builds notes from the pull requests merged since the previous release, with categories from `.github/release.yml` (or `.yaml`). Nothing is saved; returns `{ name, body }`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_name": { "type": "string", "description": "Tag for the release." }, "target_commitish": { "type": "string", "description": "Used when the tag doesn't exist yet (default: the default branch)." }, "previous_tag_name": { "type": "string", "description": "Start from this tag (default: the newest earlier published release)." }, "configuration_file_path": { "type": "string", "description": "Config file to use instead of `.github/release.yml`." } }, "required": [ "tag_name" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/latest": { "get": { "operationId": "getReposByOwnerByRepoReleasesLatest", "summary": "Get the latest release", "description": "The release marked latest, or else the newest published release that isn't a prerelease. 404 when there is none.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/releases/tags/{tag}": { "get": { "operationId": "getReposByOwnerByRepoReleasesTagsByTag", "summary": "Get a release by tag", "description": "Published releases only; drafts aren't found by tag.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Releases" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "tag", "in": "path", "required": true, "description": "tag", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/blobs": { "post": { "operationId": "postReposByOwnerByRepoGitBlobs", "summary": "Create a blob", "description": "Push protection applies: content that looks like a credential is refused with 422. Returns `{ url, sha }`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The blob's content." }, "encoding": { "type": "string", "description": "`utf-8` (default) or `base64`." } }, "required": [ "content" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/blobs/{sha}": { "get": { "operationId": "getReposByOwnerByRepoGitBlobsBySha", "summary": "Get a blob", "description": "Content is base64-encoded; send `Accept: application/vnd.github.raw` for the raw bytes.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "path", "required": true, "description": "sha", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/commits": { "post": { "operationId": "postReposByOwnerByRepoGitCommits", "summary": "Create a Git commit", "description": "Writes a commit object; no branch moves until you update a reference. `author` and `committer` default to you. Commits made by agents carry a `diffinery-agent` header.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Commit message." }, "tree": { "type": "string", "description": "SHA of the commit's tree." }, "parents": { "type": "array", "items": { "type": "string" }, "description": "Parent commit SHAs (none for a root commit)." }, "author": { "type": "object", "description": "`{ name, email, date }`." }, "committer": { "type": "object", "description": "`{ name, email, date }` (default: the author)." }, "signature": { "type": "string", "description": "Signature to store in the commit as given." } }, "required": [ "message", "tree" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/commits/{sha}": { "get": { "operationId": "getReposByOwnerByRepoGitCommitsBySha", "summary": "Get a Git commit", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "path", "required": true, "description": "sha", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/matching-refs/{ref}": { "get": { "operationId": "getReposByOwnerByRepoGitMatchingRefsByRef", "summary": "List matching references", "description": "Refs whose names start with `refs/{ref}`, like `heads/feature` or `tags/v1.`. Pull request refs appear only when `ref` starts with `pull/`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 100, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/ref/{ref}": { "get": { "operationId": "getReposByOwnerByRepoGitRefByRef", "summary": "Get a reference", "description": "`ref` is the name after `refs/`, like `heads/main` or `tags/v1.0`, and must match exactly.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/refs": { "get": { "operationId": "getReposByOwnerByRepoGitRefs", "summary": "List all references", "description": "Every branch, tag and other ref, without pull request refs.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 100, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoGitRefs", "summary": "Create a reference", "description": "Branch protection and agent rules apply as they do to a push.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "description": "Full ref name, like `refs/heads/feature`." }, "sha": { "type": "string", "description": "Commit to point at." } }, "required": [ "ref", "sha" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/refs/{path}": { "get": { "operationId": "getReposByOwnerByRepoGitRefsByPath", "summary": "List references", "description": "Every ref under `refs/{path}`, for example `heads` or `tags/v1`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoGitRefsByPath", "summary": "Update a reference", "description": "Access: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sha": { "type": "string", "description": "New target commit." }, "force": { "type": "boolean", "description": "Allow a non-fast-forward update." } }, "required": [ "sha" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoGitRefsByPath", "summary": "Delete a reference", "description": "Access: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "Path inside the repository, or a ref name after `refs/`.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/tags": { "post": { "operationId": "postReposByOwnerByRepoGitTags", "summary": "Create a tag object", "description": "Writes an annotated tag object only; create its `refs/tags/...` reference with `POST /repos/{owner}/{repo}/git/refs` to publish it.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "string", "description": "Tag name." }, "object": { "type": "string", "description": "SHA of the object to tag." }, "message": { "type": "string", "description": "Tag message." }, "type": { "type": "string", "description": "`commit`, `tree`, `blob` or `tag`; must match the object (default: its type)." }, "tagger": { "type": "object", "description": "`{ name, email, date }` (default: you)." } }, "required": [ "tag", "object" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/tags/{sha}": { "get": { "operationId": "getReposByOwnerByRepoGitTagsBySha", "summary": "Get a tag object", "description": "`verification.verified` is always false.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "path", "required": true, "description": "sha", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/trees": { "post": { "operationId": "postReposByOwnerByRepoGitTrees", "summary": "Create a tree", "description": "Applies the entries on top of `base_tree`. An entry with `content` creates a blob (push protection applies); one with `sha: null` deletes the path. `type` is ignored: the mode decides. At most 10000 entries per request.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tree": { "type": "array", "description": "Entries: `{ path, mode, sha }` or `{ path, mode, content }`. `mode` is `100644` (default), `100755`, `040000`, `160000` or `120000`." }, "base_tree": { "type": "string", "description": "Tree to start from (default: an empty tree)." } }, "required": [ "tree" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/git/trees/{sha}": { "get": { "operationId": "getReposByOwnerByRepoGitTreesBySha", "summary": "Get a tree", "description": "`sha` may be a tree, a commit or a ref. `truncated` is true when a recursive listing stopped at 100000 entries.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Git database" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "path", "required": true, "description": "sha", "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "required": false, "description": "Any value but `0` or `false` lists every entry below, not just the top level.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/branches": { "get": { "operationId": "getReposByOwnerByRepoBranches", "summary": "List branches", "description": "Each branch says whether it is `protected` and the `default`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Branches and tags" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/branches/{branch}": { "get": { "operationId": "getReposByOwnerByRepoBranchesByBranch", "summary": "Get a branch", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Branches and tags" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "description": "Branch name (for protection rules: a branch name or pattern).", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/merges": { "post": { "operationId": "postReposByOwnerByRepoMerges", "summary": "Merge a branch", "description": "Merges `head` into the `base` branch with a merge commit. Returns 201 with the commit, 204 when `base` already contains `head`, 409 on a conflict and 404 when either doesn't exist. Branch protection and agent rules apply as they do to a push.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Branches and tags" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base": { "type": "string", "description": "Branch to merge into." }, "head": { "type": "string", "description": "Branch, tag or commit to merge." }, "commit_message": { "type": "string", "description": "Commit message (default: `Merge {head} into {base}`)." } }, "required": [ "base", "head" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/tags": { "get": { "operationId": "getReposByOwnerByRepoTags", "summary": "List tags", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Branches and tags" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits/{ref}/status": { "get": { "operationId": "getReposByOwnerByRepoCommitsByRefStatus", "summary": "Get the combined status", "description": "The latest status per context and an overall `state`: `failure` if any is `error` or `failure`, `pending` if any is pending or there are none, else `success`. Check runs aren't included.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commit statuses" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Statuses per page (default 100, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits/{ref}/statuses": { "get": { "operationId": "getReposByOwnerByRepoCommitsByRefStatuses", "summary": "List commit statuses", "description": "Every status for the commit, newest first, including older ones for the same context.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commit statuses" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/deployments/{id}/statuses/{status}": { "get": { "operationId": "getReposByOwnerByRepoDeploymentsByIdStatusesByStatus", "summary": "Get a deployment status", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commit statuses" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "status", "in": "path", "required": true, "description": "status", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/statuses/{ref}": { "get": { "operationId": "getReposByOwnerByRepoStatusesByRef", "summary": "List commit statuses for a ref", "description": "Same as `GET /repos/{owner}/{repo}/commits/{ref}/statuses`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commit statuses" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/statuses/{sha}": { "post": { "operationId": "postReposByOwnerByRepoStatusesBySha", "summary": "Create a commit status", "description": "`sha` may also be a branch or tag. Statuses show with the checks, and a required check in branch protection can name a `context`; one account's status never replaces another's for that. At most 1000 statuses per commit and context. Sends the `status` webhook. See [Checks and statuses](/docs/collaboration/checks-and-statuses).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Commit statuses" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "path", "required": true, "description": "sha", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`error`, `failure`, `pending` or `success`." }, "target_url": { "type": "string", "description": "http(s) link to details." }, "description": { "type": "string", "description": "Short description (cut at 1024 characters)." }, "context": { "type": "string", "description": "Label that tells statuses apart (default `default`)." } }, "required": [ "state" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/check-runs": { "post": { "operationId": "postReposByOwnerByRepoCheckRuns", "summary": "Create or update a check run", "description": "For external CI and integrations. A check with the same name on the same commit is updated. Required checks in branch protection can name it.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Check name." }, "head_sha": { "type": "string", "description": "Commit the check is for." }, "status": { "type": "string", "description": "`queued` (default), `in_progress` or `completed`." }, "conclusion": { "type": "string", "description": "With `completed`: `success`, `failure`, `neutral`, `cancelled`, `skipped` or `timed_out`." }, "details_url": { "type": "string", "description": "Link to more detail." }, "output": { "type": "object", "description": "`{ title, summary }`." } }, "required": [ "name", "head_sha" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/check-runs/{id}": { "get": { "operationId": "getReposByOwnerByRepoCheckRunsById", "summary": "Get a check run", "description": "`id` is the numeric id, Diffinery's own, or the id of the Actions job that reports it (a job's `check_run_url` points here).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoCheckRunsById", "summary": "Update a check run", "description": "Only the account that created the check run can update it, and runs from Diffinery Actions can't be changed. A `conclusion` completes the run. Annotations add to the existing ones (50 per request, 1000 in all).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." }, "status": { "type": "string", "description": "`queued`, `in_progress`, `completed`, `waiting`, `requested` or `pending`." }, "conclusion": { "type": "string", "description": "`action_required`, `cancelled`, `failure`, `neutral`, `success`, `skipped`, `stale` or `timed_out`." }, "details_url": { "type": "string", "description": "http(s) link to more detail." }, "external_id": { "type": "string", "description": "Your own reference for the run." }, "started_at": { "type": "string", "description": "ISO timestamp." }, "completed_at": { "type": "string", "description": "ISO timestamp." }, "output": { "type": "object", "description": "`{ title, summary, text, annotations }`." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/check-runs/{id}/annotations": { "get": { "operationId": "getReposByOwnerByRepoCheckRunsByIdAnnotations", "summary": "List check run annotations", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/check-suites/{id}": { "get": { "operationId": "getReposByOwnerByRepoCheckSuitesById", "summary": "Get a check suite", "description": "`id` is a workflow run id or `app-{app}-{sha}`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/check-suites/{id}/check-runs": { "get": { "operationId": "getReposByOwnerByRepoCheckSuitesByIdCheckRuns", "summary": "List a check suite's check runs", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits/{ref}/check-runs": { "get": { "operationId": "getReposByOwnerByRepoCommitsByRefCheckRuns", "summary": "List check runs for a commit", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits/{ref}/check-suites": { "get": { "operationId": "getReposByOwnerByRepoCommitsByRefCheckSuites", "summary": "List check suites for a commit", "description": "Diffinery derives check suites from check runs: one per workflow run, and one per app (id `app-{app}-{sha}`) for external check runs. `head_branch` is always null and `pull_requests` empty.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Checks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits": { "get": { "operationId": "getReposByOwnerByRepoCommits", "summary": "List commits", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commits" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "query", "required": false, "description": "Branch, tag or commit to start from (default: the default branch).", "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": false, "description": "Only commits that touch this path.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits/{ref}": { "get": { "operationId": "getReposByOwnerByRepoCommitsByRef", "summary": "Get a commit", "description": "The commit with its diff.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commits" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "ref", "in": "path", "required": true, "description": "Branch, tag or commit SHA.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/commits/{sha}/pulls": { "get": { "operationId": "getReposByOwnerByRepoCommitsByShaPulls", "summary": "List pull requests for a commit", "description": "Pull requests whose head or merge commit is this commit, plus open pull requests (the 50 newest) that contain it. 422 when the commit doesn't exist.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commits" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "path", "required": true, "description": "sha", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/compare/{spec}": { "get": { "operationId": "getReposByOwnerByRepoCompareBySpec", "summary": "Compare two refs", "description": "`spec` is `base...head`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commits" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "spec", "in": "path", "required": true, "description": "Two refs as `base...head`.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/commits": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberCommits", "summary": "List a pull request's commits", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Commits" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/branches/{branch}/protection": { "get": { "operationId": "getReposByOwnerByRepoBranchesByBranchProtection", "summary": "Get a protection rule", "description": "`branch` is the rule's pattern.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Branch protection" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "description": "Branch name (for protection rules: a branch name or pattern).", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoBranchesByBranchProtection", "summary": "Create or replace a protection rule", "description": "`branch` is a branch name or pattern. People only: agents and workflow tokens can't change protection. `allowAgentAutoMerge` (boolean) lets agents land pull requests through auto-merge or the merge queue; turning it on or off is audited as `repo.protection.agent_auto_merge`. `agentAutoMergeWithoutApproval` (boolean, needs `allowAgentAutoMerge`) lets those landings go through on green required checks without a person's approval, audited as `repo.protection.agent_approval_waiver`. `autoMergeAgents` (agent logins, needs `allowAgentAutoMerge`) has Diffinery turn auto-merge on by itself, as the agent, for pull requests those agents open, mark ready or push to, with `autoMergeMethod` (`merge`, `squash` or `rebase`) for how they merge; the answer stores them as `{ id, login }`, and changes are audited as `repo.protection.agent_auto_merge_rule`. See the branch protection guide for every field.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Branch protection" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "description": "Branch name (for protection rules: a branch name or pattern).", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoBranchesByBranchProtection", "summary": "Delete a protection rule", "description": "Audited as `repo.protection.delete`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Branch protection" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "description": "Branch name (for protection rules: a branch name or pattern).", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues": { "get": { "operationId": "getReposByOwnerByRepoIssues", "summary": "List issues and pull requests", "description": "As on GitHub, this list includes pull requests. The total is in the `X-Total-Count` header.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`open` (default), `closed` or `all`.", "schema": { "type": "string" } }, { "name": "labels", "in": "query", "required": false, "description": "Only items with this label.", "schema": { "type": "string" } }, { "name": "creator", "in": "query", "required": false, "description": "Only items opened by this login.", "schema": { "type": "string" } }, { "name": "milestone", "in": "query", "required": false, "description": "A milestone number, `none` (no milestone) or `*` (any milestone).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Text search in titles.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoIssues", "summary": "Create an issue", "description": "Needs a signed-in caller, also on a public repository. As on GitHub, `labels` and `assignees` from a caller without triage access are dropped without an error.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title." }, "body": { "type": "string", "description": "Markdown body." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Label names." }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "Logins." } }, "required": [ "title" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}": { "get": { "operationId": "getReposByOwnerByRepoIssuesByNumber", "summary": "Get an issue", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoIssuesByNumber", "summary": "Update an issue", "description": "The author can edit their own issue or pull request. As on GitHub, `labels`, `assignees` and `milestone` from a caller without triage access are dropped without an error.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title." }, "body": { "type": "string", "description": "New body." }, "state": { "type": "string", "description": "`open` or `closed`." }, "state_reason": { "type": "string", "description": "Why it was closed, like `completed` or `not_planned`." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Replace the labels." }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "Replace the assignees." }, "milestone": { "type": "integer", "description": "Milestone number, or `null` to remove the milestone. Ignored without triage access. Checked before anything is saved: 422 when it isn't a whole number or `null`, or when no milestone has that number." } }, "required": [] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/assignees": { "post": { "operationId": "postReposByOwnerByRepoIssuesByNumberAssignees", "summary": "Add assignees", "description": "Adds to the current assignees, at most 10 in all. Logins aren't checked against who can be assigned. Returns the issue.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignees": { "type": "array", "items": { "type": "string" }, "description": "Logins to add." } }, "required": [] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoIssuesByNumberAssignees", "summary": "Remove assignees", "description": "Returns the issue.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignees": { "type": "array", "items": { "type": "string" }, "description": "Logins to remove." } }, "required": [] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/comments": { "get": { "operationId": "getReposByOwnerByRepoIssuesByNumberComments", "summary": "List comments", "description": "Conversation comments on an issue or pull request (not review comments).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only comments updated at or after this ISO timestamp.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoIssuesByNumberComments", "summary": "Add a comment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Markdown body." } }, "required": [ "body" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/events": { "get": { "operationId": "getReposByOwnerByRepoIssuesByNumberEvents", "summary": "List an issue's events", "description": "Labels, assignments, state changes, locks, review requests and the like, oldest first.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/labels": { "get": { "operationId": "getReposByOwnerByRepoIssuesByNumberLabels", "summary": "List an issue's labels", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoIssuesByNumberLabels", "summary": "Add labels to an issue", "description": "Labels that don't exist yet are created. At most 100 per issue. Returns the issue's labels.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" }, "description": "Label names (`{ name }` objects, or a bare array as the body, work too)." } }, "required": [ "labels" ] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoIssuesByNumberLabels", "summary": "Replace an issue's labels", "description": "Labels that don't exist yet are created; `[]` removes them all. Returns the issue's labels.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" }, "description": "Label names (`{ name }` objects, or a bare array as the body, work too)." } }, "required": [ "labels" ] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoIssuesByNumberLabels", "summary": "Remove all labels from an issue", "description": "Access: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/labels/{name}": { "delete": { "operationId": "deleteReposByOwnerByRepoIssuesByNumberLabelsByName", "summary": "Remove a label from an issue", "description": "Returns the labels left. 404 when the issue doesn't have it.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/lock": { "put": { "operationId": "putReposByOwnerByRepoIssuesByNumberLock", "summary": "Lock a conversation", "description": "While locked, only people with triage access can comment, review or react.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "lock_reason": { "type": "string", "description": "`off-topic`, `too heated`, `resolved` or `spam`." } }, "required": [] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoIssuesByNumberLock", "summary": "Unlock a conversation", "description": "Access: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/reactions": { "get": { "operationId": "getReposByOwnerByRepoIssuesByNumberReactions", "summary": "List reactions to an issue", "description": "Works for pull requests too.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "content", "in": "query", "required": false, "description": "Only reactions with this content.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoIssuesByNumberReactions", "summary": "Add a reaction to an issue", "description": "Needs a signed-in account, and triage access when the conversation is locked. Returns 201 for a new reaction, or 200 with the existing one when you had already reacted with that content.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket` or `eyes`." } }, "required": [ "content" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/reactions/{reaction}": { "delete": { "operationId": "deleteReposByOwnerByRepoIssuesByNumberReactionsByReaction", "summary": "Delete a reaction from an issue", "description": "Your own reactions, or anyone's with admin access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "reaction", "in": "path", "required": true, "description": "reaction", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/{number}/timeline": { "get": { "operationId": "getReposByOwnerByRepoIssuesByNumberTimeline", "summary": "List an issue's timeline", "description": "Events, comments (`commented`) and reviews (`reviewed`) together, oldest first.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/comments": { "get": { "operationId": "getReposByOwnerByRepoIssuesComments", "summary": "List comments in a repository", "description": "Conversation comments on every issue and pull request.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only comments updated at or after this ISO timestamp.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created` (default) or `updated`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` (default) or `desc`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/comments/{id}": { "get": { "operationId": "getReposByOwnerByRepoIssuesCommentsById", "summary": "Get a comment", "description": "`id` is the numeric id or Diffinery's own.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoIssuesCommentsById", "summary": "Edit a comment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "New Markdown body." } }, "required": [ "body" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoIssuesCommentsById", "summary": "Delete a comment", "description": "Your own comments, or anyone's with maintain access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/comments/{id}/reactions": { "get": { "operationId": "getReposByOwnerByRepoIssuesCommentsByIdReactions", "summary": "List reactions to a comment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "content", "in": "query", "required": false, "description": "Only reactions with this content.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoIssuesCommentsByIdReactions", "summary": "Add a reaction to a comment", "description": "Needs a signed-in account, and triage access when the conversation is locked. Returns 201 for a new reaction, or 200 with the existing one when you had already reacted with that content.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket` or `eyes`." } }, "required": [ "content" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/comments/{id}/reactions/{reaction}": { "delete": { "operationId": "deleteReposByOwnerByRepoIssuesCommentsByIdReactionsByReaction", "summary": "Delete a reaction from a comment", "description": "Your own reactions, or anyone's with admin access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "reaction", "in": "path", "required": true, "description": "reaction", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/events": { "get": { "operationId": "getReposByOwnerByRepoIssuesEvents", "summary": "List events in a repository", "description": "Events on every issue and pull request, newest first, each with its `issue`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/issues/events/{id}": { "get": { "operationId": "getReposByOwnerByRepoIssuesEventsById", "summary": "Get an event", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/labels": { "get": { "operationId": "getReposByOwnerByRepoLabels", "summary": "List labels", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoLabels", "summary": "Create a label", "description": "422 when a label with that name exists; change one with `PATCH /repos/{owner}/{repo}/labels/{name}`.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Label name, at most 100 characters." }, "color": { "type": "string", "description": "6-digit hex color, with or without `#` (default `ededed`)." }, "description": { "type": "string", "description": "Description." } }, "required": [ "name" ] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/labels/{name}": { "get": { "operationId": "getReposByOwnerByRepoLabelsByName", "summary": "Get a label", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoLabelsByName", "summary": "Update a label", "description": "Renaming it renames it on every issue too.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_name": { "type": "string", "description": "New name." }, "color": { "type": "string", "description": "6-digit hex color, with or without `#`." }, "description": { "type": "string", "description": "Description." } }, "required": [] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoLabelsByName", "summary": "Delete a label", "description": "Also removes it from every issue.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/milestones": { "get": { "operationId": "getReposByOwnerByRepoMilestones", "summary": "List milestones", "description": "Every milestone in the state you ask for (no paging), ordered by due date (milestones without one last), then by number. The `id` is the milestone number. Milestones come from GitHub imports or are created with the endpoint below; the web UI sets an issue's milestone but doesn't create milestones.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`open` (default), `closed` or `all`. Anything else is 422.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoMilestones", "summary": "Create a milestone", "description": "New milestones are open unless `state` is `closed`. There is no endpoint to delete a milestone.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "1 to 255 characters." }, "description": { "type": "string", "description": "At most 65,536 characters." }, "state": { "type": "string", "description": "`open` (default) or `closed`." }, "due_on": { "type": "string", "description": "ISO 8601 timestamp, or `null`." } }, "required": [ "title" ] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/milestones/{number}": { "get": { "operationId": "getReposByOwnerByRepoMilestonesByNumber", "summary": "Get a milestone", "description": "`number` is the milestone number. 404 `milestone not found`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoMilestonesByNumber", "summary": "Update a milestone", "description": "Send only the fields you change. Closing records `closed_at`; reopening clears it.\n\nAccess: Triage access to the repository. Tokens need the `write` scope.", "tags": [ "Issues" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "1 to 255 characters." }, "description": { "type": "string", "description": "At most 65,536 characters." }, "state": { "type": "string", "description": "`open` or `closed`." }, "due_on": { "type": "string", "description": "ISO 8601 timestamp, or `null` to clear it." } }, "required": [] } } } }, "x-diffinery-access": "triage", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls": { "get": { "operationId": "getReposByOwnerByRepoPulls", "summary": "List pull requests", "description": "The total is in the `X-Total-Count` header.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`open` (default), `closed` or `all`.", "schema": { "type": "string" } }, { "name": "labels", "in": "query", "required": false, "description": "Only pull requests with this label.", "schema": { "type": "string" } }, { "name": "creator", "in": "query", "required": false, "description": "Only pull requests opened by this login.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Text search in titles.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoPulls", "summary": "Open a pull request", "description": "A workflow's `GITHUB_TOKEN` can open one only when the repository allows workflows to create pull requests (`can_approve_pull_request_reviews`, see `PUT /repos/{owner}/{repo}/actions/permissions/workflow`); otherwise 403.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title." }, "head": { "type": "string", "description": "Branch with the changes (`owner:branch` also works)." }, "base": { "type": "string", "description": "Branch to merge into (default: the default branch)." }, "body": { "type": "string", "description": "Markdown description." }, "intent": { "type": "string", "description": "Diffinery: what the change is meant to do, shown to reviewers." }, "draft": { "type": "boolean", "description": "Open as a draft." }, "reviewers": { "type": "array", "items": { "type": "string" }, "description": "Logins to request reviews from." }, "auto_merge": { "type": "boolean", "description": "Diffinery: `true` turns on auto-merge as it opens, `false` keeps it off where your setting would turn it on. When asked for and it stayed off (for example, the base branch has no required checks), the answer's `auto_merge_skipped` says why. See /docs/collaboration/merge-on-green." } }, "required": [ "title", "head" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumber", "summary": "Get a pull request", "description": "Includes `mergeable`, `mergeable_state`, `merge_blockers` (why it can't merge yet), `approvals`, `required_approvals` and `checks`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoPullsByNumber", "summary": "Update a pull request", "description": "The author, or anyone with triage access. `base` isn't supported and is ignored. A merged pull request can't be reopened. A title or body change sends a `pull_request` `edited` event. `draft` is a Diffinery extension (GitHub only offers it through GraphQL): the author or anyone with write access can set it on an open pull request. It records a `ready_for_review` or `convert_to_draft` timeline event and sends the `pull_request` webhook with the action `ready_for_review` or `converted_to_draft`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title." }, "body": { "type": "string", "description": "New description." }, "state": { "type": "string", "description": "`open` or `closed`." }, "draft": { "type": "boolean", "description": "`false` marks it ready for review; `true` converts it back to a draft." } }, "required": [] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/auto-merge": { "put": { "operationId": "putReposByOwnerByRepoPullsByNumberAutoMerge", "summary": "Enable auto-merge", "description": "Diffinery's REST form of GitHub's `enablePullRequestAutoMerge`. Diffinery merges the pull request by itself as soon as every rule of its base branch is met (required checks on the head, approvals from people, linear history), as the caller, never bypassing anything; into a branch with a merge queue it adds it to the queue instead. Returns `{ state, auto_merge, merge_commit_sha }`: `state` is `enabled` (waiting), `queued` or `merged` (it was ready). The pull request's `auto_merge` shows it until then. A push to the head branch by anyone else, or converting the pull request to a draft, turns it off. 422 for a draft, a closed or merged pull request, or one already in the merge queue. Agents and workflow tokens may use it on the default branch or a protected one only when its rule sets `allowAgentAutoMerge` (else 403) and has at least one required check (else 422); a workflow token needs `contents: write`. Audited as `pull_request.auto_merge_enabled`, and the merge as `pull_request.auto_merged`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "merge_method": { "type": "string", "description": "`merge`, `squash` or `rebase` (default: the queue's method, `squash` where linear history is required, else `merge`)." }, "commit_title": { "type": "string", "description": "Title of the merge or squash commit." }, "commit_message": { "type": "string", "description": "Body of the merge or squash commit." }, "delete_branch": { "type": "boolean", "description": "Delete the head branch once auto-merge lands the pull request, directly or through the queue (never the default branch or a protected one). 422 `delete_branch must be a boolean` otherwise." }, "sha": { "type": "string", "description": "Turn auto-merge on only if the head is still this commit (409 if it moved)." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoPullsByNumberAutoMerge", "summary": "Disable auto-merge", "description": "GitHub's `disablePullRequestAutoMerge`. Anyone with write access may turn it off, whoever turned it on; a workflow token needs `contents: write`. 204 even when it was off, which records nothing. Otherwise it records an `auto_merge_disabled` event, sends a `pull_request` webhook with that action, and is audited as `pull_request.auto_merge_disabled`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/comments": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberComments", "summary": "List review comments", "description": "Line comments from reviews.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoPullsByNumberComments", "summary": "Create a review comment", "description": "Adds one line comment as its own `COMMENTED` review, on the current head; `commit_id` is ignored and `position` is read as a line number, not a diff position. Multi-line comments aren't supported. With `in_reply_to`, replies to that comment instead. 422 on a closed pull request.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Markdown body." }, "path": { "type": "string", "description": "File path (required unless replying)." }, "line": { "type": "integer", "description": "Line number (required unless replying)." }, "side": { "type": "string", "description": "`RIGHT` (default) or `LEFT`." }, "position": { "type": "integer", "description": "Used as `line` when `line` is missing." }, "commit_id": { "type": "string", "description": "Accepted and ignored." }, "in_reply_to": { "type": "integer", "description": "Review comment id to reply to; its path and line are used." } }, "required": [ "body" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/comments/{id}/replies": { "post": { "operationId": "postReposByOwnerByRepoPullsByNumberCommentsByIdReplies", "summary": "Reply to a review comment", "description": "Adds a reply on the same line, as its own `COMMENTED` review.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Markdown body." } }, "required": [ "body" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/diffinery/agent-review": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberDiffineryAgentReview", "summary": "Get a pull request's agent review", "description": "The pull request's review task (each review is a run of it), the last reviewed head (`reviewed_sha`) and every finding: `id`, `path`, `line`, `side`, `severity` (`blocking` or `not_blocking`), `title`, `body`, `suggestion`, `state` (`open`, `fixed` or `dismissed`), `fixed_in` and the review `comment_id`. Needs write access.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoPullsByNumberDiffineryAgentReview", "summary": "Ask for an agent review", "description": "Reviews the pull request now, or once its current review ends, whatever the trigger setting. People with write access only (any of their tokens); agents can't ask. 422 when agent review is off; 429 past a daily limit (the repository's, or 20 reviews of one pull request in 24 hours). Audited as `review.request`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/files": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberFiles", "summary": "List changed files", "description": "Each file with its status, additions, deletions and patch.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/merge": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberMerge", "summary": "Check mergeability", "description": "Whether the pull request can merge now, and if not, the blockers.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoPullsByNumberMerge", "summary": "Merge a pull request", "description": "Fails with 405 and the blockers when protection rules aren't met, and with 405 when a merge commit is asked for on a branch that requires linear history (without `merge_method`, such a branch squashes). A branch that requires a merge queue answers 405 too: add the pull request to the queue instead. A repository admin (a person, not an agent or a workflow) can bypass, when the rule doesn't include administrators, there are no conflicts and the pull request isn't a draft. Each flag covers only what it names: `bypass_rules: true` skips unmet rules and linear history, and `bypass_merge_queue: true` skips only the queue. A bypass that skipped an unmet rule, linear history or the queue is audited as `pull_request.merge_bypassed`. Agents can't merge into the default branch or a protected branch themselves (unless the rule sets `agentsMayMerge`); where it sets `allowAgentAutoMerge` they turn on auto-merge (`PUT .../auto-merge`) instead.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "merge_method": { "type": "string", "description": "`merge`, `squash` or `rebase`." }, "commit_title": { "type": "string", "description": "Title of the merge or squash commit." }, "commit_message": { "type": "string", "description": "Body of the merge or squash commit." }, "sha": { "type": "string", "description": "Fail if the head has moved from this commit." }, "delete_branch": { "type": "boolean", "description": "Delete the head branch after merging." }, "bypass_merge_queue": { "type": "boolean", "description": "Merge directly even when a queue is required (admins). Doesn't skip unmet rules; send `bypass_rules` too for that." }, "bypass_rules": { "type": "boolean", "description": "Merge even though protection rules (including linear history) aren't met (admins). Without it, an admin's merge is blocked like anyone else's." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/requested_reviewers": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberRequestedReviewers", "summary": "List requested reviewers", "description": "Returns `{ users, teams }`; `teams` is always empty.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoPullsByNumberRequestedReviewers", "summary": "Request reviewers", "description": "The author, or anyone with triage access. Team reviewers aren't supported: a non-empty `team_reviewers` fails with 422. Sends the `pull_request` webhook (`review_requested`). Returns the pull request.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewers": { "type": "array", "items": { "type": "string" }, "description": "Logins." }, "team_reviewers": { "type": "array", "items": { "type": "string" }, "description": "Must be empty or absent." } }, "required": [] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoPullsByNumberRequestedReviewers", "summary": "Remove requested reviewers", "description": "The author, or anyone with triage access. Teams aren't supported. Returns the pull request.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reviewers": { "type": "array", "items": { "type": "string" }, "description": "Logins to remove." } }, "required": [] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/reviews": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberReviews", "summary": "List reviews", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoPullsByNumberReviews", "summary": "Submit a review", "description": "Only people's approvals count toward required approvals: agents' and workflows' don't. A workflow's `GITHUB_TOKEN` can approve or request changes only when the repository allows it (`can_approve_pull_request_reviews`); otherwise 403.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "`APPROVE`, `REQUEST_CHANGES` or `COMMENT` (default)." }, "body": { "type": "string", "description": "Review summary." }, "comments": { "type": "array", "description": "Line comments: `{ path, line, side: \"LEFT\" | \"RIGHT\", body }`." } }, "required": [] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/reviews/{id}": { "get": { "operationId": "getReposByOwnerByRepoPullsByNumberReviewsById", "summary": "Get a review", "description": "`id` is the numeric id or Diffinery's own.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/reviews/{id}/dismissals": { "put": { "operationId": "putReposByOwnerByRepoPullsByNumberReviewsByIdDismissals", "summary": "Dismiss a review", "description": "Only approvals and change requests can be dismissed. Needs maintain access; agents and the pull request's author can't dismiss. `event` is ignored. Returns the review.\n\nAccess: Maintain access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Why the review is dismissed." } }, "required": [ "message" ] } } } }, "x-diffinery-access": "maintain", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/update-branch": { "put": { "operationId": "putReposByOwnerByRepoPullsByNumberUpdateBranch", "summary": "Update a pull request's branch", "description": "Merges the base branch into the head branch right away, then answers 202 as GitHub does. 422 when the base has no new commits, on a conflict, or when `expected_head_sha` doesn't match. Branch protection and agent rules apply to the head branch.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_head_sha": { "type": "string", "description": "Fail unless the head branch is at this commit." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/comments": { "get": { "operationId": "getReposByOwnerByRepoPullsComments", "summary": "List review comments in a repository", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only comments updated at or after this ISO timestamp.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`created` (default) or `updated`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`asc` (default) or `desc`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/comments/{id}": { "get": { "operationId": "getReposByOwnerByRepoPullsCommentsById", "summary": "Get a review comment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoPullsCommentsById", "summary": "Edit a review comment", "description": "Your own comments, or anyone's with maintain access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "New Markdown body." } }, "required": [ "body" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoPullsCommentsById", "summary": "Delete a review comment", "description": "Your own comments, or anyone's with maintain access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/comments/{id}/reactions": { "get": { "operationId": "getReposByOwnerByRepoPullsCommentsByIdReactions", "summary": "List reactions to a review comment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "content", "in": "query", "required": false, "description": "Only reactions with this content.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoPullsCommentsByIdReactions", "summary": "Add a reaction to a review comment", "description": "Needs a signed-in account, and triage access when the conversation is locked. Returns 201 for a new reaction, or 200 with the existing one when you had already reacted with that content.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "`+1`, `-1`, `laugh`, `confused`, `heart`, `hooray`, `rocket` or `eyes`." } }, "required": [ "content" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/comments/{id}/reactions/{reaction}": { "delete": { "operationId": "deleteReposByOwnerByRepoPullsCommentsByIdReactionsByReaction", "summary": "Delete a reaction from a review comment", "description": "Your own reactions, or anyone's with admin access.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Pull requests" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "reaction", "in": "path", "required": true, "description": "reaction", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/merge-queue/{branch}": { "get": { "operationId": "getReposByOwnerByRepoMergeQueueByBranch", "summary": "Get a branch's merge queue", "description": "Diffinery only (GitHub exposes this through GraphQL). Settings and every entry with its merge group and checks.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Merge queue" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "branch", "in": "path", "required": true, "description": "Branch name (for protection rules: a branch name or pattern).", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/pulls/{number}/merge-queue": { "put": { "operationId": "putReposByOwnerByRepoPullsByNumberMergeQueue", "summary": "Add a pull request to the merge queue", "description": "Diffinery only. Returns 201 with the entry when queued.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Merge queue" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "merge_method": { "type": "string", "description": "`merge`, `squash` or `rebase` (default: the queue's method)." }, "delete_branch": { "type": "boolean", "description": "Delete the head branch once merged." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoPullsByNumberMergeQueue", "summary": "Remove a pull request from the merge queue", "description": "Access: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Merge queue" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/deployments": { "get": { "operationId": "getReposByOwnerByRepoDeployments", "summary": "List deployments", "description": "Newest first. Each filter matches exactly.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Deployments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "sha", "in": "query", "required": false, "description": "Full commit SHA.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Ref, as given when the deployment was created.", "schema": { "type": "string" } }, { "name": "task", "in": "query", "required": false, "description": "Task name.", "schema": { "type": "string" } }, { "name": "environment", "in": "query", "required": false, "description": "Environment name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoDeployments", "summary": "Create a deployment", "description": "Unless `required_contexts` is `[]`, every check and status on the commit (or each context you name) must have passed, else 409; checks and statuses reported by agents don't count toward the default set. Creates the environment if needed and sends the `deployment` webhook. Environment names are case-insensitive: an existing environment keeps its spelling, and any spelling of `production` is a production environment. `auto_merge` is ignored. See [Environments](/docs/actions/environments).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Deployments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "description": "Branch, tag or commit to deploy." }, "task": { "type": "string", "description": "Task name (default `deploy`)." }, "payload": { "type": "object", "description": "Extra data for the deployer (a string is kept as is)." }, "environment": { "type": "string", "description": "Environment name (default `production`)." }, "description": { "type": "string", "description": "Short description." }, "transient_environment": { "type": "boolean", "description": "Transient deployments aren't made inactive by later successful ones." }, "production_environment": { "type": "boolean", "description": "Default: true when the environment is `production`." }, "required_contexts": { "type": "array", "items": { "type": "string" }, "description": "Contexts that must have passed; `[]` skips the check." } }, "required": [ "ref" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/deployments/{id}": { "get": { "operationId": "getReposByOwnerByRepoDeploymentsById", "summary": "Get a deployment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Deployments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoDeploymentsById", "summary": "Delete a deployment", "description": "Refused with 422 while its latest status is `success`, unless it is the only deployment in its environment. Deletes its statuses too.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Deployments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/deployments/{id}/statuses": { "get": { "operationId": "getReposByOwnerByRepoDeploymentsByIdStatuses", "summary": "List deployment statuses", "description": "Newest first.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Deployments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoDeploymentsByIdStatuses", "summary": "Create a deployment status", "description": "A `success` status marks older successful deployments to the same environment inactive (except transient and production ones) unless `auto_inactive` is false. A different `environment` moves the deployment there. Sends the `deployment_status` webhook.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Deployments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`error`, `failure`, `inactive`, `in_progress`, `queued`, `pending` or `success`." }, "log_url": { "type": "string", "description": "http(s) link to the deployment's output." }, "target_url": { "type": "string", "description": "Older name for `log_url`, used when `log_url` is missing." }, "environment_url": { "type": "string", "description": "http(s) link to the deployed environment." }, "description": { "type": "string", "description": "Short description (cut at 140 characters)." }, "environment": { "type": "string", "description": "Move the deployment to this environment." }, "auto_inactive": { "type": "boolean", "description": "`false` keeps older deployments active (default `true`)." } }, "required": [ "state" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments": { "get": { "operationId": "getReposByOwnerByRepoEnvironments", "summary": "List environments", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}": { "get": { "operationId": "getReposByOwnerByRepoEnvironmentsByEnv", "summary": "Get an environment", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoEnvironmentsByEnv", "summary": "Create or update an environment", "description": "People only; agents can't change environments. Required reviewers and a wait timer hold a job that names the environment before anything starts, until a reviewer approves and the timer has passed. Fields left out keep their values. Audited. See [Required reviewers and wait timers](/docs/actions/environments#required-reviewers-and-wait-timers).\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment_branch_policy": { "type": "object", "description": "`{ protected_branches, custom_branch_policies }` with exactly one true, or `null` to allow every ref." }, "wait_timer": { "type": "integer", "description": "Minutes a job waits before it deploys, 0 to 43200." }, "reviewers": { "type": "array", "description": "Up to 6 people with access, as `{type: \"User\", id}` (the numeric id the API shows) or `{type: \"User\", login}`. Never agents; Diffinery has no teams. `[]` or `null` removes them." }, "prevent_self_review": { "type": "boolean", "description": "Whoever started a run (or an earlier attempt, or owns the agent that did) can't approve it." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoEnvironmentsByEnv", "summary": "Delete an environment", "description": "Deletes its secrets and variables too. People only. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}/deployment-branch-policies": { "get": { "operationId": "getReposByOwnerByRepoEnvironmentsByEnvDeploymentBranchPolicies", "summary": "List deployment branch policies", "description": "The branch and tag patterns of an environment with `custom_branch_policies`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoEnvironmentsByEnvDeploymentBranchPolicies", "summary": "Create a deployment branch policy", "description": "The environment must have `custom_branch_policies`. Tag patterns never match tags last pushed by an agent. People only. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Branch or tag name pattern, like `release/*`." }, "type": { "type": "string", "description": "`branch` (default) or `tag`." } }, "required": [ "name" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}/deployment-branch-policies/{id}": { "delete": { "operationId": "deleteReposByOwnerByRepoEnvironmentsByEnvDeploymentBranchPoliciesById", "summary": "Delete a deployment branch policy", "description": "People only. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}/secrets": { "get": { "operationId": "getReposByOwnerByRepoEnvironmentsByEnvSecrets", "summary": "List environment secrets", "description": "Names and dates only; values are never returned.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}/secrets/{name}": { "get": { "operationId": "getReposByOwnerByRepoEnvironmentsByEnvSecretsByName", "summary": "Get an environment secret", "description": "Name and dates only.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoEnvironmentsByEnvSecretsByName", "summary": "Set an environment secret", "description": "People only. Names are upper-cased, and `GITHUB_` names are refused. The value is encrypted at rest; GitHub's sealed-box `encrypted_value` isn't supported. The first secret on an environment without a branch policy limits it to protected branches. Returns 201 for a new secret and 204 for a replaced one. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Secret value." } }, "required": [ "value" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoEnvironmentsByEnvSecretsByName", "summary": "Delete an environment secret", "description": "People only. Audited.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}/variables": { "get": { "operationId": "getReposByOwnerByRepoEnvironmentsByEnvVariables", "summary": "List environment variables", "description": "Access: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 10, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoEnvironmentsByEnvVariables", "summary": "Create an environment variable", "description": "409 when it exists. Names are upper-cased, and `GITHUB_` names are refused. People only. Audited as `environment.variable.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Variable name." }, "value": { "type": "string", "description": "Variable value." } }, "required": [ "name", "value" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/environments/{env}/variables/{name}": { "get": { "operationId": "getReposByOwnerByRepoEnvironmentsByEnvVariablesByName", "summary": "Get an environment variable", "description": "Access: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoEnvironmentsByEnvVariablesByName", "summary": "Update an environment variable", "description": "People only. Renaming onto a name that exists fails with 409. Audited as `environment.variable.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name (renames the variable)." }, "value": { "type": "string", "description": "New value." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoEnvironmentsByEnvVariablesByName", "summary": "Delete an environment variable", "description": "People only. Audited as `environment.variable.delete`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Environments" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "env", "in": "path", "required": true, "description": "env", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/actions/secrets": { "get": { "operationId": "getOrgsByOrgActionsSecrets", "summary": "List organization secrets", "description": "Names, update times and `visibility` (`all`, `private` or `selected`), never values.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/actions/secrets/{name}": { "get": { "operationId": "getOrgsByOrgActionsSecretsByName", "summary": "Get an organization secret", "description": "Its name, update time and `visibility`, never the value. 404 when there is no such secret.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putOrgsByOrgActionsSecretsByName", "summary": "Set an organization secret", "description": "Creates or updates the secret. `visibility` says which of the organization's repositories get it: `all` (the default for a new secret), `private` (private and internal ones) or `selected` (those in `selected_repository_ids`). An update without them keeps the secret's visibility and selection. Names are upper-cased and must match `[A-Z_][A-Z0-9_]*`. People only. Audited as `org.secret.set`. See /docs/actions/secrets-and-variables#organization-secrets.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Secret value." }, "visibility": { "type": "string", "description": "`all`, `private` or `selected` (422 otherwise)." }, "selected_repository_ids": { "type": "array", "items": { "type": "integer" }, "description": "With `selected`: the repositories' numeric ids. An id that isn't one of the organization's repositories gets 422." } }, "required": [ "value" ] } } } }, "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrgActionsSecretsByName", "summary": "Delete an organization secret", "description": "People only. 404 when the organization has no secret with this name. Audited as `org.secret.delete`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/actions/secrets/{name}/repositories": { "get": { "operationId": "getOrgsByOrgActionsSecretsByNameRepositories", "summary": "List a secret's selected repositories", "description": "`{ total_count, repositories }` for a secret with `visibility: selected`; 409 `the secret's visibility isn't selected` otherwise.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putOrgsByOrgActionsSecretsByNameRepositories", "summary": "Replace a secret's selected repositories", "description": "Only for a secret with `visibility: selected` (409 otherwise). A repository that leaves the selection stops getting the secret from its next job. Audited as `org.secret.repositories`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selected_repository_ids": { "type": "array", "items": { "type": "integer" }, "description": "Every repository that should get the secret." } }, "required": [ "selected_repository_ids" ] } } } }, "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/actions/secrets/{name}/repositories/{repoId}": { "put": { "operationId": "putOrgsByOrgActionsSecretsByNameRepositoriesByRepoId", "summary": "Add a repository to a secret's selection", "description": "Only for a secret with `visibility: selected` (409 otherwise). `repoId` is the repository's numeric id. Audited as `org.secret.repository.add`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "repoId", "in": "path", "required": true, "description": "repoId", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrgActionsSecretsByNameRepositoriesByRepoId", "summary": "Remove a repository from a secret's selection", "description": "Only for a secret with `visibility: selected` (409 otherwise). The repository stops getting the secret from its next job. Audited as `org.secret.repository.remove`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "repoId", "in": "path", "required": true, "description": "repoId", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/actions/variables": { "get": { "operationId": "getOrgsByOrgActionsVariables", "summary": "List organization variables", "description": "Actions variables shared by every repository of the organization: workflows read them as `vars.NAME`, and a repository variable with the same name wins. Returns `total_count` and every variable (no paging) with `name`, `value`, `visibility` (always `all`), `created_at` and `updated_at`. Organization owners and admins who are people (agents get 403 `organization admins only`); anyone outside the organization gets 404.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `read` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postOrgsByOrgActionsVariables", "summary": "Create an organization variable", "description": "Creates the variable, or replaces the value of one with that name (GitHub answers 409 instead). Names are stored upper-cased; they must start with a letter or `_`, contain only letters, digits and `_`, and not start with `GITHUB_` (422 `invalid variable name`). Values are strings of at most 49,152 characters (422 `value must be a string of at most 48 KB`). GitHub's `visibility` and `selected_repository_ids` are ignored: every repository of the organization gets the variable. People only. Audited as `org.variable_set`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Variable name." }, "value": { "type": "string", "description": "Variable value, at most 49,152 characters." } }, "required": [ "name", "value" ] } } } }, "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/actions/variables/{name}": { "get": { "operationId": "getOrgsByOrgActionsVariablesByName", "summary": "Get an organization variable", "description": "`name` is matched in upper case. 404 `variable not found`. Organization owners and admins who are people.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `read` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchOrgsByOrgActionsVariablesByName", "summary": "Update an organization variable", "description": "Sets the value, creating the variable if it doesn't exist. Renaming isn't supported: a `name` in the body is ignored. Same name and value rules as creating. People only. Audited as `org.variable_set`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "New value, at most 49,152 characters." } }, "required": [ "value" ] } } } }, "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrgActionsVariablesByName", "summary": "Delete an organization variable", "description": "404 when the organization has no variable with this name, and nothing is audited. People only. Audited as `org.variable_delete`.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/secrets": { "get": { "operationId": "getReposByOwnerByRepoActionsSecrets", "summary": "List repository secrets", "description": "Names and update times only; values are never returned.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/secrets/{name}": { "put": { "operationId": "putReposByOwnerByRepoActionsSecretsByName", "summary": "Set a repository secret", "description": "People only. The value is encrypted at rest. GitHub's sealed-box `encrypted_value` isn't supported; send `value` over HTTPS. Audited as `repo.secret.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Secret value." } }, "required": [ "value" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoActionsSecretsByName", "summary": "Delete a repository secret", "description": "People only. Audited as `repo.secret.delete`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/variables": { "get": { "operationId": "getReposByOwnerByRepoActionsVariables", "summary": "List repository variables", "description": "The repository's own variables. Workflows in an organization's repositories also see the organization's variables (`GET /orgs/{org}/actions/variables`), and a repository variable with the same name wins.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoActionsVariables", "summary": "Create a repository variable", "description": "409 when the repository already has a variable with this name. An organization variable of the same name doesn't count, and the repository's wins in workflows. Names are stored upper-cased. People only. Audited as `repo.variable.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Variable name." }, "value": { "type": "string", "description": "Variable value." } }, "required": [ "name", "value" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/variables/{name}": { "get": { "operationId": "getReposByOwnerByRepoActionsVariablesByName", "summary": "Get a repository variable", "description": "404 for a name only the organization has. `created_at` and `updated_at` are always null.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoActionsVariablesByName", "summary": "Set a repository variable", "description": "Diffinery's form: creates the variable or replaces its value. GitHub clients use `POST` and `PATCH`. Names are stored upper-cased. People only. Audited as `repo.variable.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Variable value." } }, "required": [ "value" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoActionsVariablesByName", "summary": "Update a repository variable", "description": "404 when the repository has no variable with this name; organization variables aren't changed here. People only. Renaming onto a name that exists fails with 409. Audited as `repo.variable.set`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name (renames the variable)." }, "value": { "type": "string", "description": "New value." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoActionsVariablesByName", "summary": "Delete a repository variable", "description": "People only. Names are matched without regard to letter case. Audited as `repo.variable.delete`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions secrets and variables" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/artifacts": { "get": { "operationId": "getReposByOwnerByRepoActionsArtifacts", "summary": "List artifacts", "description": "Every artifact in the repository, newest first. Each has a numeric `id`, `name`, `size_in_bytes`, `digest` (`sha256:...` when the uploader sent one), `created_at`, `expires_at`, `expired`, an `archive_download_url`, and `workflow_run` (its `id` is the run number). An artifact past its retention stays listed with `expired: true` for 90 more days; its content is already deleted. Returns `{ total_count, artifacts }`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Only artifacts with exactly this name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/artifacts/{id}": { "get": { "operationId": "getReposByOwnerByRepoActionsArtifactsById", "summary": "Get an artifact", "description": "`id` is the artifact's numeric id. Expired artifacts are returned too, with `expired: true`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoActionsArtifactsById", "summary": "Delete an artifact", "description": "Deletes the artifact and its content, expired or not; it no longer counts toward the repository's artifact quota. 404 when there is no artifact with that id. Audited as `actions.artifact.delete`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/artifacts/{id}/{format}": { "get": { "operationId": "getReposByOwnerByRepoActionsArtifactsByIdByFormat", "summary": "Download an artifact", "description": "`format` must be `zip` (anything else is 404). Redirects with 302 to a signed URL that works for 10 minutes and needs no token; follow redirects (`curl -L`). The content is a zip, or the file itself for an artifact uploaded as a single unzipped file. 410 `Artifact has expired` once the artifact has expired.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "format", "in": "path", "required": true, "description": "Archive format: `zip`.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "302": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/cache/usage": { "get": { "operationId": "getReposByOwnerByRepoActionsCacheUsage", "summary": "Get cache usage", "description": "`full_name`, `active_caches_size_in_bytes` and `active_caches_count` of the saved entries. A repository keeps up to 10 GB of caches; see [Limits](/docs/reference/limits#caches-and-artifacts).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/caches": { "get": { "operationId": "getReposByOwnerByRepoActionsCaches", "summary": "List caches", "description": "Saved cache entries; uploads in progress aren't listed. Each has a numeric `id`, `key`, `version`, `ref` (the ref it was saved for, like `refs/heads/main`), `size_in_bytes`, `created_at` and `last_accessed_at`. Returns `{ total_count, actions_caches }`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Only entries whose key starts with this.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Only entries saved for this full ref, like `refs/heads/main`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`last_accessed_at` (default), `created_at` or `size_in_bytes`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`desc` (default) or `asc`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoActionsCaches", "summary": "Delete caches by key", "description": "Deletes every entry whose key is exactly `key` (all versions), or only those saved for `ref`. Returns the deleted entries as `{ total_count, actions_caches }`. 422 `key is required` without `key`, 404 when nothing matched. Audited as `actions.cache.delete`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "description": "The exact cache key.", "schema": { "type": "string" } }, { "name": "ref", "in": "query", "required": false, "description": "Only entries saved for this full ref, like `refs/heads/main`.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/caches/{id}": { "delete": { "operationId": "deleteReposByOwnerByRepoActionsCachesById", "summary": "Delete a cache", "description": "By the entry's numeric id. 404 when there is none. Audited as `actions.cache.delete`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{runId}/artifacts": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsByRunIdArtifacts", "summary": "List a run's artifacts", "description": "Newest first, in the same shape as `GET /repos/{owner}/{repo}/actions/artifacts`. `runId` is the run's id, or its number (`github.run_id` in workflows), which covers every attempt of the run. Expired artifacts are listed with `expired: true`; their content is gone.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions artifacts and caches" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "Workflow run id, or the run number (`github.run_id`).", "schema": { "type": "string" } }, { "name": "name", "in": "query", "required": false, "description": "Only artifacts with exactly this name.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/jobs/{id}": { "get": { "operationId": "getReposByOwnerByRepoActionsJobsById", "summary": "Get a job", "description": "The job with its steps. GitHub's job fields, plus Diffinery's own: `runner` (the hosted container's `image`, `location` and `instance`; `null` on a self-hosted runner) and `placementTries` (how many times a hosted job went back in line before a runner took it: no free container, or a runner on a replaced image) and `restarts` (how many times it started over because the platform replaced its runner before its steps ran). See /docs/actions/runners.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/jobs/{id}/logs": { "get": { "operationId": "getReposByOwnerByRepoActionsJobsByIdLogs", "summary": "Get a job's logs", "description": "Plain text, one timestamped line each, or JSON with `format=json`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "`json` for an array of `{ t, text }` lines.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Only lines after this sequence number (for following a live log).", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/jobs/{id}/rerun": { "post": { "operationId": "postReposByOwnerByRepoActionsJobsByIdRerun", "summary": "Re-run a job", "description": "Starts a new attempt of the job's run that runs this job (this matrix leg) and every job that depends on it; the other jobs are kept from the earlier attempt as they were. Answers `{ run_id }`, the new attempt's id. 409 when the run hasn't finished. A workflow's `GITHUB_TOKEN` can't re-run workflows (403).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enable_debug_logging": { "type": "boolean", "description": "Accepted and ignored." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/permissions/workflow": { "get": { "operationId": "getReposByOwnerByRepoActionsPermissionsWorkflow", "summary": "Get workflow token permissions", "description": "The defaults for the `GITHUB_TOKEN` of the repository's workflows (GitHub's \"Workflow permissions\" setting). `default_workflow_permissions` is what a job without `permissions:` gets: `read` (contents and packages read, nothing else) or `write` (read and write on every scope except `id-token`). `can_approve_pull_request_reviews` says whether job tokens may open pull requests and approve or request changes. `agent_runs_use_secrets` (a Diffinery addition, `false` by default) says whether runs of code an agent wrote get the repository's and organization's secrets. New repositories start with `read` and `false`; repositories created before the setting existed have `write` and `false`. See [Workflow permissions](/docs/actions/workflow-permissions).\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoActionsPermissionsWorkflow", "summary": "Set workflow token permissions", "description": "Send only what changes. People only: agents get 403 `only people can change what workflows are allowed to do`. Applies to jobs that start afterwards. Each change is audited as `repo.actions_workflow_settings`. Even when allowed, a workflow's approval never counts toward required approvals.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_workflow_permissions": { "type": "string", "description": "`read` or `write`." }, "can_approve_pull_request_reviews": { "type": "boolean", "description": "Allow workflows' `GITHUB_TOKEN` to open pull requests and to approve or request changes." }, "agent_runs_use_secrets": { "type": "boolean", "description": "Give runs of code an agent wrote (an agent triggered the run, pushed its branch last, or opened or pushed to its pull request) the repository's and organization's secrets. Default `false`." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runners": { "get": { "operationId": "getReposByOwnerByRepoActionsRunners", "summary": "List self-hosted runners", "description": "GitHub's shape: `{ total_count, runners }`, each with `id`, `name`, `os`, `status` (`online` when it polled in the last 90 seconds, otherwise `offline`), `busy`, `ephemeral` and `labels`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runners/{id}": { "delete": { "operationId": "deleteReposByOwnerByRepoActionsRunnersById", "summary": "Remove a self-hosted runner", "description": "Its runner token stops working at once. A job it is running carries on with its own job token. Audited as `runner.remove`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runners/claim": { "post": { "operationId": "postReposByOwnerByRepoActionsRunnersClaim", "summary": "Claim a job for a self-hosted runner", "description": "Used by `diffinery runner`. Send the runner's `drn_` token and an empty body: the runner offers the name and labels it registered with. Only registered runners claim: a personal token, even a repository admin's, gets 403 `personal tokens can't claim jobs; register this runner: ...`. Returns 204 when no queued job matches the labels, otherwise the job with a fresh job token. See /docs/actions/runners.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runners/register": { "post": { "operationId": "postReposByOwnerByRepoActionsRunnersRegister", "summary": "Register a self-hosted runner", "description": "Trades a registration token for the runner's own `drn_` token, shown once, which can claim this repository's jobs and nothing else. No `Authorization` header: the registration token is the credential. A wrong or expired token, or a repository that doesn't exist, gets 401 `invalid or expired registration token`. At most 100 runners per repository and 20 labels per runner (429 past the runner limit). Returns `{ id, name, labels, ephemeral, token }`. Audited as `runner.register`, with the admin who created the registration token as the actor.\n\nAccess: No authentication needed.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_token": { "type": "string", "description": "A `drg_` token from `POST .../actions/runners/registration-token`." }, "name": { "type": "string", "description": "Runner name (default `runner`)." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels the runner offers, matched against `runs-on`." }, "ephemeral": { "type": "boolean", "description": "`true` for a single job: the runner's token stops working once it takes a job, and the runner is removed when the job finishes." } }, "required": [ "registration_token" ] } } } }, "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runners/registration-token": { "post": { "operationId": "postReposByOwnerByRepoActionsRunnersRegistrationToken", "summary": "Create a runner registration token", "description": "As on GitHub: a `drg_` token that registers any number of self-hosted runners with this repository for an hour. Returns `{ token, expires_at }`. People only: agents, job tokens and sandbox tokens get 403 `only repository admins can add self-hosted runners`. Audited as `runner.registration_token`. See /docs/actions/runners#manage-runners.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs": { "get": { "operationId": "getReposByOwnerByRepoActionsRuns", "summary": "List workflow runs", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "workflow", "in": "query", "required": false, "description": "Workflow file path.", "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "description": "Head branch.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Run status or conclusion.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Triggering event.", "schema": { "type": "string" } }, { "name": "head_sha", "in": "query", "required": false, "description": "Head commit.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 25, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsById", "summary": "Get a workflow run", "description": "The run with its jobs. `id` is the run's id, or its number (`github.run_id` in workflows), which picks the latest attempt.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/approvals": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsByIdApprovals", "summary": "List a run's deployment reviews", "description": "Each reviewer's decision, with the environment and comment.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/attempts/{attempt}": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsByIdAttemptsByAttempt", "summary": "Get a run attempt", "description": "Re-runs are stored as separate runs with the same run number; this returns attempt `attempt` of the run's number.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "attempt", "in": "path", "required": true, "description": "attempt", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/cancel": { "post": { "operationId": "postReposByOwnerByRepoActionsRunsByIdCancel", "summary": "Cancel a run", "description": "Access: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/jobs": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsByIdJobs", "summary": "List a run's jobs", "description": "Each job as `GET .../actions/jobs/{id}` returns it, with `runner`, `placementTries` and `restarts`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/logs": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsByIdLogs", "summary": "Download a run's logs", "description": "A zip with one text file per job. Jobs past 24 MB of logs in total are left out.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoActionsRunsByIdLogs", "summary": "Delete a run's logs", "description": "Deletes every job's log and step summary for good; the run, its jobs, checks and artifacts stay. Only for a finished run (409 otherwise). An agent can delete only the logs of runs that didn't run on the default branch or a protected branch, and a workflow's `GITHUB_TOKEN` can't delete logs (403). Audited as `repo.actions.logs.delete`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/pending_deployments": { "get": { "operationId": "getReposByOwnerByRepoActionsRunsByIdPendingDeployments", "summary": "List the environments a run waits on", "description": "Environments whose required reviewers or wait timer hold the run's jobs, with `current_user_can_approve` for the caller. See [Required reviewers and wait timers](/docs/actions/environments#required-reviewers-and-wait-timers).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoActionsRunsByIdPendingDeployments", "summary": "Approve or reject a run's pending deployments", "description": "Only a listed reviewer, signed in or with a `write` token: never an agent, a workflow's token or a sandbox token (403). With `prevent_self_review`, not whoever started the run (403). One decision per environment and run counts; 422 when nothing waits. Approved jobs start once their wait timer has passed; rejected ones fail. Returns the deployments of the jobs that were waiting. Audited as `deployment.approve` or `deployment.reject`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment_ids": { "type": "array", "description": "Ids of the environments to decide." }, "state": { "type": "string", "description": "`approved` or `rejected`." }, "comment": { "type": "string", "description": "Shown with the decision and in the audit log." } }, "required": [ "environment_ids", "state" ] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/rerun": { "post": { "operationId": "postReposByOwnerByRepoActionsRunsByIdRerun", "summary": "Re-run a workflow run", "description": "Starts a new attempt that runs every job again. Answers `{ run_id }`, the new attempt's id. A workflow's `GITHUB_TOKEN` can't re-run workflows (403).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enable_debug_logging": { "type": "boolean", "description": "Accepted and ignored." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/runs/{id}/rerun-failed-jobs": { "post": { "operationId": "postReposByOwnerByRepoActionsRunsByIdRerunFailedJobs", "summary": "Re-run a run's failed jobs", "description": "Starts a new attempt that runs the jobs and matrix legs that failed, were cancelled or timed out, and every job that depends on them. The others are kept from the earlier attempt as they were, with their logs and artifacts. Answers `{ run_id }`, the new attempt's id. 409 `this run has no failed jobs to re-run`, or when the run hasn't finished. A workflow's `GITHUB_TOKEN` can't re-run workflows (403).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enable_debug_logging": { "type": "boolean", "description": "Accepted and ignored." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/workflows": { "get": { "operationId": "getReposByOwnerByRepoActionsWorkflows", "summary": "List workflows", "description": "Each workflow file with its triggers, and parse errors for invalid ones (`state: invalid`).\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/workflows/{workflow}": { "get": { "operationId": "getReposByOwnerByRepoActionsWorkflowsByWorkflow", "summary": "Get a workflow", "description": "`workflow` is the file path or file name; the response's `id` is the path. `created_at` and `updated_at` are the time of the request, not of the file.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "workflow", "in": "path", "required": true, "description": "Workflow file path (URL-encoded) or file name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/workflows/{workflow}/dispatches": { "post": { "operationId": "postReposByOwnerByRepoActionsWorkflowsByWorkflowDispatches", "summary": "Run a workflow (workflow_dispatch)", "description": "`workflow` is the file path or name, URL-encoded, like `.github%2Fworkflows%2Fdeploy.yml` or `deploy.yml`. Returns the new run's id. Fails with 429 when the repository already has 500 unfinished workflow runs.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "workflow", "in": "path", "required": true, "description": "Workflow file path (URL-encoded) or file name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "description": "Branch or tag to run on." }, "inputs": { "type": "object", "description": "Values for `on.workflow_dispatch.inputs`." } }, "required": [ "ref" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/actions/workflows/{workflow}/runs": { "get": { "operationId": "getReposByOwnerByRepoActionsWorkflowsByWorkflowRuns", "summary": "List a workflow's runs", "description": "No `Link` header; page with `total_count`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Actions" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "workflow", "in": "path", "required": true, "description": "Workflow file path (URL-encoded) or file name.", "schema": { "type": "string" } }, { "name": "branch", "in": "query", "required": false, "description": "Head branch.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Run status or conclusion.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Triggering event.", "schema": { "type": "string" } }, { "name": "head_sha", "in": "query", "required": false, "description": "Head commit.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/hooks": { "get": { "operationId": "getReposByOwnerByRepoHooks", "summary": "List webhooks", "description": "Secrets are never returned.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Webhooks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoHooks", "summary": "Create a webhook", "description": "`config.url` must be `https://` to a public host: `localhost`, single-label, `.local` and `.internal` names, private, loopback and link-local addresses get 422 `webhook URL must be a public host`, and Diffinery's own host 422 `webhook URL can't point at Diffinery itself`. At most 20 webhooks per repository (422). Audited as `repo.webhook.create`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Webhooks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "description": "`{ url, secret }`. The secret signs each delivery (`X-Hub-Signature-256`)." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event names, or `[\"*\"]` (default) for all." } }, "required": [ "config" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/hooks/{id}": { "delete": { "operationId": "deleteReposByOwnerByRepoHooksById", "summary": "Delete a webhook", "description": "Audited as `repo.webhook.delete`.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Webhooks" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{owner}/packages": { "get": { "operationId": "getOrgsByOwnerPackages", "summary": "List an organization's packages", "description": "Only packages you can pull.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{owner}/packages/{type}/{name}": { "get": { "operationId": "getOrgsByOwnerPackagesByTypeByName", "summary": "Get one of an organization's packages", "description": "`type` is `container`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchOrgsByOwnerPackagesByTypeByName", "summary": "Update one of an organization's packages", "description": "Change its visibility or the repository it is linked to.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "description": "`private` or `public`." }, "repository": { "type": "string", "description": "Repository name to link, or `null` to unlink." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOwnerPackagesByTypeByName", "summary": "Delete one of an organization's packages", "description": "Access: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{owner}/packages/{type}/{name}/versions": { "get": { "operationId": "getOrgsByOwnerPackagesByTypeByNameVersions", "summary": "List package versions", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`tagged` for tagged versions only.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{owner}/packages/{type}/{name}/versions/{id}": { "get": { "operationId": "getOrgsByOwnerPackagesByTypeByNameVersionsById", "summary": "Get a package version", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOwnerPackagesByTypeByNameVersionsById", "summary": "Delete a package version", "description": "Access: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/packages": { "get": { "operationId": "getReposByOwnerByRepoPackages", "summary": "List a repository's packages", "description": "Container images linked to the repository.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/packages": { "get": { "operationId": "getUserPackages", "summary": "List your packages", "description": "Only packages you can pull.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Packages" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/packages/{type}/{name}": { "get": { "operationId": "getUserPackagesByTypeByName", "summary": "Get one of your packages", "description": "`type` is `container`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchUserPackagesByTypeByName", "summary": "Update one of your packages", "description": "Change its visibility or the repository it is linked to.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "description": "`private` or `public`." }, "repository": { "type": "string", "description": "Repository name to link, or `null` to unlink." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUserPackagesByTypeByName", "summary": "Delete one of your packages", "description": "Access: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/packages/{type}/{name}/versions": { "get": { "operationId": "getUserPackagesByTypeByNameVersions", "summary": "List package versions", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`tagged` for tagged versions only.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/packages/{type}/{name}/versions/{id}": { "get": { "operationId": "getUserPackagesByTypeByNameVersionsById", "summary": "Get a package version", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUserPackagesByTypeByNameVersionsById", "summary": "Delete a package version", "description": "Access: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{owner}/packages": { "get": { "operationId": "getUsersByOwnerPackages", "summary": "List a user's packages", "description": "Only packages you can pull.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{owner}/packages/{type}/{name}": { "get": { "operationId": "getUsersByOwnerPackagesByTypeByName", "summary": "Get one of a user's packages", "description": "`type` is `container`.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchUsersByOwnerPackagesByTypeByName", "summary": "Update one of a user's packages", "description": "Change its visibility or the repository it is linked to.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "description": "`private` or `public`." }, "repository": { "type": "string", "description": "Repository name to link, or `null` to unlink." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUsersByOwnerPackagesByTypeByName", "summary": "Delete one of a user's packages", "description": "Access: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{owner}/packages/{type}/{name}/versions": { "get": { "operationId": "getUsersByOwnerPackagesByTypeByNameVersions", "summary": "List package versions", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`tagged` for tagged versions only.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{owner}/packages/{type}/{name}/versions/{id}": { "get": { "operationId": "getUsersByOwnerPackagesByTypeByNameVersionsById", "summary": "Get a package version", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUsersByOwnerPackagesByTypeByNameVersionsById", "summary": "Delete a package version", "description": "Access: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Packages" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "description": "Package type: `container`.", "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "description": "Name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/linked-accounts/{id}": { "delete": { "operationId": "deleteDiffineryAdminLinkedAccountsById", "summary": "Clear anyone's GitHub link", "description": "For example after an account changes hands. `id` is the link id from `GET /diffinery/user/linked-accounts` of the account that owns it; there is no endpoint that lists other people's links. 404 `link not found`, 403 `site admin only`. Audited as `account.link_cleared`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports": { "get": { "operationId": "getDiffineryImports", "summary": "List your imports", "description": "The imports you started, newest first, at most 100. Repository imports that belong to an organization import aren't listed separately; read them through the organization import's `children`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Imports" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDiffineryImports", "summary": "Start a GitHub import", "description": "Imports one GitHub repository (`source`), or many repositories of a GitHub organization or user (`source_owner`), on the server, and returns the import (`status: queued`). Git history with LFS objects is copied in a container; issues and pull requests (with their numbers), comments, reviews, labels, milestones, branch protection, Actions variables, deployment environments and releases come through GitHub's REST API. Secret values are never read: only secret names are listed in `summary`, for a person to set by hand. People can import into their own account or an organization they own or administer (site administrators: any user or organization). An agent can import only where its owner may (the owner's own account or an organization the owner owns or administers; an organization's agent, only into that organization), and only when its policy allows `write`; its imports always use `secrets: stop` and skip Actions variables and environments. Needs a `write` or `admin` token (403 `starting an import needs a token with write or admin scope`), or a browser session. At most one organization import and three repository imports run at a time per account and per target (429), and a `source` repository larger than `IMPORT_MAX_REPO_KB` (default 10 GB, by GitHub's reported size) is refused with 422. Other errors: 422 `/ already exists; choose another name`, 422 `GitHub repository was not found or the token cannot read it`, 422 `GitHub rejected the token (expired or revoked?)`, 429 when GitHub's rate limit is reached, 502 `could not reach GitHub: ...`. Audited as `import.create`. See [Migrate from GitHub](/docs/migrate-from-github).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope.", "tags": [ "Imports" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "description": "One repository: `owner/name`, a github.com or GitHub Enterprise URL, or an SSH remote such as `git@github.com:owner/name.git`. Send either `source` or `source_owner`." }, "source_owner": { "type": "string", "description": "A GitHub organization or user: imports its repositories (private ones too when the token can see them)." }, "owner": { "type": "string", "description": "The Diffinery user or organization that will own the new repositories." }, "name": { "type": "string", "description": "`source` only: the new repository's name. Default: the GitHub name. It must not exist yet." }, "visibility": { "type": "string", "description": "`keep` (default: public stays public, private and internal become private), `private` or `public`. `internal` is accepted and means `private`." }, "github_token": { "type": "string", "description": "A GitHub token that can read the source, at most 400 characters. Needed for private repositories; Actions variables, secret names and branch protection need a token with admin access to the source. Encrypted at rest, used only by this import, deleted when it ends, never returned." }, "github_api_url": { "type": "string", "description": "GitHub Enterprise Server: the REST API base, such as `https://ghe.example.com/api/v3` (default `https://api.github.com`). Must be HTTPS on a public host. Required, on the same host as `source`, when `source` names an Enterprise host and you send `github_token`." }, "options": { "type": "object", "description": "What to copy; each is `true` by default: `issues` (issues and pull requests with comments and reviews), `labels` (labels and milestones), `branch_protection`, `variables` (Actions variables, secret names and deployment environments), `releases`, `lfs`. Plus `secrets`: `bypass` (default: credentials found in old history are imported with an audited push protection bypass, which needs a person with admin on the target and an `admin` token or browser session) or `stop` (the import fails). Unknown keys are refused with 422." }, "repositories": { "type": "array", "items": { "type": "string" }, "description": "`source_owner` only: the repository names to import, at most 1,000. Default: every repository (up to 1,000)." }, "exclude_forks": { "type": "boolean", "description": "`source_owner` only: skip forks (default `false`)." }, "exclude_archived": { "type": "boolean", "description": "`source_owner` only: skip archived repositories (default `false`)." }, "concurrency": { "type": "integer", "description": "`source_owner` only: repositories imported at the same time, 1 to 8 (default 3)." } }, "required": [ "owner" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}": { "get": { "operationId": "getDiffineryImportsById", "summary": "Get an import", "description": "Readable by the person or agent who started it, by people who could start an import into the same target (the account itself, or the organization's owners and admins), and by site administrators; others get 404 `import not found`. Fields: `kind` (`repository` or `organization`), `status` (`draft`, `queued`, `running`, `succeeded`, `failed` or `cancelled`), `attempt`, `source`, `target`, `visibility`, `options`, `steps` (each with `name`, `title`, `status`, `message`, `count` and times), `git` (the transfer's `phase`, `message`, `chunks`, `bytes` and `tries`), `summary` (counts, secret names, variables, environments, releases, push protection `findings`, linked and imported people), `warnings`, `error` and timestamps. An organization import adds `children` (each repository import's `id`, `source`, `target`, `status`, current `step` and `error`), and a draft adds `candidates`. Credentials are never included. Poll until `status` is `succeeded`, `failed` or `cancelled`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/agent/complete": { "post": { "operationId": "postDiffineryImportsByIdAgentComplete", "summary": "Report a Git transfer's result (import agent)", "description": "Internal: the import agent reports the result (branches, tags, pull request heads, LFS objects, push protection findings, warnings). Revokes the push token and wakes the import's workflow. Same credential rules as the spec. 204.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/agent/progress": { "post": { "operationId": "postDiffineryImportsByIdAgentProgress", "summary": "Report Git transfer progress (import agent)", "description": "Internal: the import agent reports its phase, a message, and the chunks and bytes pushed so far. Same credential rules as the spec. 204.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/agent/spec": { "get": { "operationId": "getDiffineryImportsByIdAgentSpec", "summary": "Get a Git transfer spec (import agent)", "description": "Internal: called by the import container with the import's own push token, which works only on Git, Git LFS and these agent endpoints. Says what to clone and where to push, and includes the GitHub token, so no other credential is accepted (403 `this token does not belong to this import`, or 403 `this push token is no longer current for the import` for a token from an earlier try; 409 `this import is not running`).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/cancel": { "post": { "operationId": "postDiffineryImportsByIdCancel", "summary": "Cancel an import", "description": "Stops a `draft`, `queued` or `running` import (409 `the import already ` otherwise): ends its workflow and container and revokes its push tokens. Cancelling an organization import cancels its unfinished repository imports. A repository the import already created is kept with what was copied so far, and is unlocked. Anyone who can read the import can cancel it. Audited as `import.cancel`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/claim": { "post": { "operationId": "postDiffineryImportsByIdClaim", "summary": "Claim an import's Git transfer (local development)", "description": "Only when the Worker runs with `IMPORT_GIT_AGENT=external` (the `dev` environment, where containers don't run); 404 otherwise. Whoever started the import gets `{ token }`, a push token for the transfer, and runs the runner image's import mode by hand with `DIFFINERY_API_URL`, `DIFFINERY_IMPORT_ID` and `DIFFINERY_IMPORT_TOKEN`. 409 `this import is not waiting for an agent`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/retry": { "post": { "operationId": "postDiffineryImportsByIdRetry", "summary": "Retry an import", "description": "Runs a `failed` or `cancelled` import again as a new `attempt` (409 `only failed or cancelled imports can be retried` otherwise), with the same options. Only whoever started it can retry it (404 for anyone else), except that a person who may import into the target can also retry an import an agent started. A repository import inside an organization import can't be retried on its own (422 `retry the organization import this repository belongs to`); retrying the organization import re-runs its failed and cancelled repositories, except those that failed because the target name was taken. The GitHub token was deleted when the import ended, so send `github_token` again for a private source. The retry resumes into the repository the import created, and fails if someone else has written to it since (`repository already holds content not written by this import; start a new import`). An agent can't retry once the repository exists (403 `an agent cannot retry an import after the repository was created; a person who administers must retry it`). Audited as `import.retry`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "github_token": { "type": "string", "description": "A GitHub token for this attempt (optional; at most 400 characters)." } }, "required": [] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/imports/{id}/selection": { "post": { "operationId": "postDiffineryImportsByIdSelection", "summary": "Choose repositories for a draft import", "description": "An organization import started from the web form waits as a `draft` with its `candidates` until its repositories are chosen; this starts it. Names are matched to the candidates ignoring case, and names that aren't candidates are dropped. 422 `choose at least one repository`, 409 `this import has already started`. Only whoever started it (404 for anyone else). Imports started through this API or MCP never wait as drafts. Unstarted drafts are cancelled after 7 days. Audited as `import.create`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repositories": { "type": "array", "items": { "type": "string" }, "description": "Names of the repositories to import, at most 1,000." } }, "required": [ "repositories" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/user/linked-accounts": { "get": { "operationId": "getDiffineryUserLinkedAccounts", "summary": "List your linked GitHub accounts", "description": "Each link has `id`, `host` (`github.com` or the Enterprise host), `apiBase`, `login`, `externalId` (GitHub's numeric user id) and `createdAt`. Imports attribute a GitHub user's issues, pull requests, comments, reviews and releases to the Diffinery account linked to that user id on the same API base. Everyone else is imported as a mannequin: login `github:`, `type: \"Mannequin\"`, linking to the GitHub profile.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Imports" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/user/linked-accounts/{id}": { "delete": { "operationId": "deleteDiffineryUserLinkedAccountsById", "summary": "Unlink a GitHub account", "description": "Removes one of your own links (an id that isn't yours changes nothing). Imports that already ran keep their attribution. Audited as `account.unlink_github`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Imports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/user/linked-accounts/github": { "post": { "operationId": "postDiffineryUserLinkedAccountsGithub", "summary": "Link a GitHub account", "description": "Step 2: reads the GitHub user's public profile and public gists without a token on the same API base, and links the account when one of the first 100 public gists GitHub lists for the user has your nonce in its description or in a file (file contents are read for at most 20 gists). Returns `{ id, host, login }`. 422 `create a PUBLIC gist whose description or a file contains , then try again`, 422 `GitHub user was not found`, 409 `GitHub user is linked to another Diffinery account`, 429 when GitHub's rate limit is reached. People only. Audited as `account.link_github`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Imports" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "description": "Your GitHub username." }, "api_url": { "type": "string", "description": "The same API base you used for the challenge. Default: github.com." } }, "required": [ "login" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/user/linked-accounts/github/challenge": { "post": { "operationId": "postDiffineryUserLinkedAccountsGithubChallenge", "summary": "Get a GitHub link code", "description": "Step 1 of linking a GitHub account without a token: returns `nonce` (`diffinery-link-` and 32 hex characters, the same each time for your account and host), `apiBase`, `host` and `gistsUrl`. Put the nonce in the description or a file of a public gist of the GitHub account, then call `POST /diffinery/user/linked-accounts/github`. People only (403 `only people can link GitHub accounts`).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Imports" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_url": { "type": "string", "description": "GitHub Enterprise REST API base, such as `https://ghe.example.com/api/v3`. Default: github.com." } }, "required": [] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/status/incidents": { "get": { "operationId": "getDiffineryAdminStatusIncidents", "summary": "List status incidents", "description": "Incidents on the status page, newest first, resolved or not: `id`, `title`, `impact`, `state`, `components`, `created_by`, `created_at`, `updated_at`, `resolved_at`, `updates` (each with `id`, `state`, `body`, `author` and `created_at`, newest first) and `html_url`. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Status page" ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "At most this many (default 50, up to 200).", "schema": { "type": "integer" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDiffineryAdminStatusIncidents", "summary": "Open a status incident", "description": "Opens an incident with its first update and answers with it. While it isn't resolved, its impact sets the status of each component it names: `critical` is a major outage, `major` a partial outage, `minor` degraded performance and `maintenance` under maintenance. Recorded in the audit log as `status_incident.create`. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Status page" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "One line, up to 200 characters." }, "impact": { "type": "string", "description": "`minor`, `major`, `critical` or `maintenance`." }, "components": { "type": "array", "description": "At least one of `web`, `git`, `actions`, `agents`, `packages` and `email`." }, "state": { "type": "string", "description": "`investigating`, `identified`, `monitoring` or `resolved`." }, "body": { "type": "string", "description": "The first update, plain text up to 5,000 characters. It is public." } }, "required": [ "title", "impact", "components", "state", "body" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/status/incidents/{id}/updates": { "post": { "operationId": "postDiffineryAdminStatusIncidentsByIdUpdates", "summary": "Post an update to a status incident", "description": "Adds an update and moves the incident to its state; `resolved` resolves it, and any other state reopens a resolved incident. Answers with the incident. Recorded in the audit log as `status_incident.resolve` when it resolves the incident and `status_incident.update` otherwise. 404 when there is no such incident, or for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Status page" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`investigating`, `identified`, `monitoring` or `resolved`." }, "body": { "type": "string", "description": "Plain text up to 5,000 characters. It is public." } }, "required": [ "state", "body" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/status": { "get": { "operationId": "getDiffineryStatus", "summary": "Get the instance's status", "description": "The status page as JSON, shaped like Statuspage's summary: `status` (`indicator`: `none`, `minor`, `major`, `critical` or `maintenance`, and a `description`), `components` (`id`, `name`, `status`: `operational`, `under_maintenance`, `degraded_performance`, `partial_outage` or `major_outage`, and a `note` when a kill switch or a database failure set it), `incidents` (the unresolved ones, newest first, each with its `updates`, newest first) and `updated_at`. Cached for 30 seconds. See [Status page](/docs/self-hosting/status-page).\n\nAccess: No authentication needed.", "tags": [ "Status page" ], "security": [], "x-diffinery-access": "public", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/early-access": { "get": { "operationId": "getDiffineryAdminEarlyAccess", "summary": "List early access requests", "description": "Requests sent through `/early-access`, newest first: `id`, `state` (`unconfirmed` until the address follows the emailed link, then `confirmed`, `invited` or `declined`), `email`, `name`, `company`, `use_case`, `hosting` (`github`, `gitlab`, `bitbucket`, `azure`, `self-hosted`, `other`, `none` or null), `confirmed_at`, `invite_id`, `decided_by`, `decided_at`, `created_at`, `updated_at` and `html_url`. 404 for anyone but a site administrator. See [Early access](/docs/accounts/early-access).\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Only requests in this state: `confirmed`, `unconfirmed`, `invited` or `declined`.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Only requests whose address, name, company or use contains this text.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "At most this many (default 100, up to 500).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/early-access/{id}": { "get": { "operationId": "getDiffineryAdminEarlyAccessById", "summary": "Get an early access request", "description": "One request, as in the list. 404 when there is none, or for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchDiffineryAdminEarlyAccessById", "summary": "Decline an early access request, or put it back", "description": "`declined` declines it; `confirmed` puts a declined request back (as `unconfirmed` if its address never confirmed). Nobody is emailed. Recorded in the audit log as `early_access.decline` or `early_access.restore`. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`declined`, or `confirmed` to put a declined request back." } }, "required": [ "state" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDiffineryAdminEarlyAccessById", "summary": "Delete an early access request", "description": "Removes the request, for someone who asks for their data to be removed. An invitation already sent from it stays; revoke it separately. Recorded in the audit log as `early_access.delete`, without the request's content or address. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/early-access/{id}/invite": { "post": { "operationId": "postDiffineryAdminEarlyAccessByIdInvite", "summary": "Invite an early access request", "description": "Sends the request's address the instance's usual invitation email (it works once for 14 days) and marks the request `invited`. An address that already has a pending instance invitation keeps it; one that already belongs to an active account is refused (422). Recorded in the audit log as `early_access.invite`, and `invite.create` when a new invitation is sent. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/email": { "get": { "operationId": "getDiffineryAdminEmail", "summary": "Email delivery status", "description": "Whether sending is configured, whether the signed bounce and complaint endpoint is on (`event_intake`), and counts for the last 24 hours.\n\nAccess: A site administrator. Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/email/suppressions": { "get": { "operationId": "getDiffineryAdminEmailSuppressions", "summary": "List suppressed email addresses", "description": "Newest first: `email`, `reason` (`hard-bounce`, `complaint` or `manual`), `detail`, `source` (`cloudflare`, `webhook`, `send` or `admin`), `created_by` and `created_at`.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Notifications and email" ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/email/suppressions/{email}": { "put": { "operationId": "putDiffineryAdminEmailSuppressionsByEmail", "summary": "Suppress an email address", "description": "Diffinery sends nothing to it until it is removed. Recorded in the audit log.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "email", "in": "path", "required": true, "description": "email", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "Why, kept with the entry." } }, "required": [] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDiffineryAdminEmailSuppressionsByEmail", "summary": "Remove an address from the suppression list", "description": "Whatever put it there. 404 when it isn't suppressed. Recorded in the audit log.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "email", "in": "path", "required": true, "description": "email", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/emails/samples": { "post": { "operationId": "postDiffineryAdminEmailsSamples", "summary": "Send yourself every email template", "description": "Access: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "only": { "type": "array", "items": { "type": "string" }, "description": "Only these sample ids." } }, "required": [] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/errors": { "get": { "operationId": "getDiffineryAdminErrors", "summary": "List unexpected server errors", "description": "The newest answers with a 5xx status, newest first: `id` (the `request_id` the answer carried, also in its `x-request-id` header), `at`, `method`, `route`, `path`, `status`, `message` and `stack`. The newest 500 are kept. No request bodies, query strings or headers are kept, and tokens in a message are masked.\n\nAccess: A site administrator. Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "At most this many (default 100, up to 500).", "schema": { "type": "integer" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/errors/{id}": { "get": { "operationId": "getDiffineryAdminErrorsById", "summary": "Get a server error by its request ID", "description": "The error a 5xx answer with this `request_id` recorded; 404 once it is no longer among the newest 500.\n\nAccess: A site administrator. Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/indexnow": { "get": { "operationId": "getDiffineryAdminIndexnow", "summary": "IndexNow submissions", "description": "What this instance has told search engines through IndexNow: `enabled` (and `off_reason` when it isn't), `key_location`, how many `site_pages` and public `repositories` it tracks, how many are `queued`, `retry_at` (set after IndexNow refused or couldn't be reached), `repositories_checked_at`, and the newest `submissions` (`at`, `urls`, `status` from IndexNow or null when unreachable, `endpoint` (the host that answered), `ms`, `error`, and the first 50 `paths`). See [Search engines](/docs/admin/site-administration#search-engines).\n\nAccess: A site administrator. Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "Submissions to return (default 50, up to 200).", "schema": { "type": "integer" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/scheduler": { "get": { "operationId": "getDiffineryAdminScheduler", "summary": "Workflow scheduler state", "description": "`tick_minutes`, `last_tick_at` (when the last check finished), `covered_until` (the last minute whose schedules were started) and `next_tick_at` (null when the timer isn't set). Tells a scheduler that stopped ticking from a run that failed to start.\n\nAccess: A site administrator. Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/security-reports": { "get": { "operationId": "getDiffineryAdminSecurityReports", "summary": "List security reports", "description": "Private vulnerability reports sent through `/security/report`, newest first: `id`, `state` (`new`, `triaged` or `resolved`), `summary`, `details`, `area`, `reply_to`, `reporter` (a login, or null when not signed in), `note`, `updated_by`, `updated_at`, `created_at` and `html_url`. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Only reports in this state: `new`, `triaged` or `resolved`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "At most this many (default 100, up to 500).", "schema": { "type": "integer" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/admin/security-reports/{id}": { "get": { "operationId": "getDiffineryAdminSecurityReportsById", "summary": "Get a security report", "description": "One report, as in the list. 404 when there is none, or for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchDiffineryAdminSecurityReportsById", "summary": "Triage or resolve a security report", "description": "Sets the report's state and note (a missing or empty note clears it). Recorded in the audit log as `security_report.triage`, `security_report.resolve` or `security_report.reopen`. 404 for anyone but a site administrator.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`triaged`, `resolved`, or `new` to reopen it." }, "note": { "type": "string", "description": "For the other site administrators, up to 2,000 characters." } }, "required": [ "state" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/emails": { "get": { "operationId": "getDiffineryEmails", "summary": "List emails sent to you", "description": "Access: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Only this kind of email.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "ISO timestamp.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "At most this many (default 50).", "schema": { "type": "integer" } }, { "name": "all", "in": "query", "required": false, "description": "`1` for everyone's (site admins).", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/emails/digest": { "post": { "operationId": "postDiffineryEmailsDigest", "summary": "Send yourself the morning digest now", "description": "Your Today digest, sent now even when the digest is off or has nothing in it, covering what happened since the last one. At most 3 an hour; more answer 429. See /docs/agents/today#the-morning-digest.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Notifications and email" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/emails/test": { "post": { "operationId": "postDiffineryEmailsTest", "summary": "Send yourself a test email", "description": "At most 5 an hour; more answer 429 `you can send at most 5 test emails an hour; try again later`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Notifications and email" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/notification-settings": { "get": { "operationId": "getDiffineryNotificationSettings", "summary": "Get your notification settings", "description": "Access: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putDiffineryNotificationSettings", "summary": "Update your notification settings", "description": "Send only the groups you want to change. The morning digest is `digest`: `email` (on or off), `hour` (0 to 23), `timeZone` (an IANA time zone such as `Europe/Istanbul` or `UTC`) and `weekends`; 422 for an hour or time zone it can't use. See /docs/agents/today#the-morning-digest.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Notifications and email" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications": { "get": { "operationId": "getNotifications", "summary": "List notifications", "description": "A token limited to repositories answers 403 `this token is limited to repositories and can't read notifications`, since notifications cover every repository.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "all", "in": "query", "required": false, "description": "`true` to include read ones.", "schema": { "type": "boolean" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putNotifications", "summary": "Mark all notifications as read", "description": "Access: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Notifications and email" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "205": { "description": "Success" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/subscription": { "get": { "operationId": "getReposByOwnerByRepoSubscription", "summary": "Get your watch setting", "description": "404 when you only get participating notifications (the default), as on GitHub.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoSubscription", "summary": "Watch or ignore a repository", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscribed": { "type": "boolean", "description": "`true` for all activity, `false` for participating only." }, "ignored": { "type": "boolean", "description": "`true` to ignore the repository." } }, "required": [] } } } }, "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoSubscription", "summary": "Stop watching a repository", "description": "Back to participating notifications.\n\nAccess: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Notifications and email" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/agents": { "get": { "operationId": "getDiffineryAgents", "summary": "List your agents", "description": "Agents you own, and agents of organizations you administer.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Tokens and agents" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDiffineryAgents", "summary": "Create an agent", "description": "People, from a browser session only (no token can create a token). Returns the agent and its first token (write scope, 90 days, unless you say otherwise). Unknown scopes or an empty list fail with 422. From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL (see /docs/security/overview#confirming-its-you).\n\nAccess: Any active account (a token, or a browser session). No token can call it: it needs a browser session.", "tags": [ "Tokens and agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "description": "Agent login." }, "name": { "type": "string", "description": "Display name." }, "org": { "type": "string", "description": "Organization that owns the agent (default: you)." }, "policy": { "type": "object", "description": "Agent policy." }, "token": { "type": "object", "description": "`{ scopes, expires_in_days }` for the first token." }, "auto_merge": { "type": "boolean", "description": "Turn on auto-merge for the pull requests it opens (see `PUT /diffinery/agents/{login}/auto-merge`)." } }, "required": [ "login" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/agents/{login}": { "delete": { "operationId": "deleteDiffineryAgentsByLogin", "summary": "Disable an agent", "description": "Its tokens stop working.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Tokens and agents" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/agents/{login}/auto-merge": { "put": { "operationId": "putDiffineryAgentsByLoginAutoMerge", "summary": "Turn auto-merge on or off for an agent's pull requests", "description": "The agent's owner, or an owner or admin of the organization that owns it. Diffinery then turns on auto-merge, as the agent, for each pull request it opens; it lands only as the agent's own auto-merge would (the repository must allow agents' auto-merge, or the agent may merge what a person approved), and a workflow change still needs a person. Same body as `PUT /diffinery/auto-merge`. Audited as `agent.auto_merge`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Tokens and agents" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "On or off." }, "merge_method": { "type": "string", "description": "`default`, `merge`, `squash` or `rebase`." } }, "required": [ "enabled" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/agents/{login}/tokens": { "post": { "operationId": "postDiffineryAgentsByLoginTokens", "summary": "Create a token for an agent", "description": "From a browser session only (no token can create a token): the agent's owner, or an owner or admin of the organization that owns it. Default scope `write`; unknown scopes or an empty list fail with 422. Audited as `agent.token.create`. From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL (see /docs/security/overview#confirming-its-you).\n\nAccess: Any active account (a token, or a browser session). No token can call it: it needs a browser session.", "tags": [ "Tokens and agents" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Token name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "`read`, `write` (default) and/or `admin`." }, "expires_in_days": { "type": "integer", "description": "Lifetime in days." } }, "required": [] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/tokens": { "get": { "operationId": "getDiffineryTokens", "summary": "List your tokens", "description": "Access: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Tokens and agents" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDiffineryTokens", "summary": "Create a token", "description": "From a browser session only: no token can create a token. The token value is returned once. Unknown scopes or an empty list fail with 422, and so does a repository you can't see (`unknown repository owner/name`). From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL (see /docs/security/overview#confirming-its-you).\n\nAccess: Any active account (a token, or a browser session). No token can call it: it needs a browser session.", "tags": [ "Tokens and agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name to recognise it by." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "`read`, `write` (default) and/or `admin`." }, "repositories": { "type": "array", "items": { "type": "string" }, "description": "Restrict to these `owner/name` repositories (only ones you can see)." }, "expires_in_days": { "type": "integer", "description": "Lifetime in days." } }, "required": [ "name" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/tokens/{id}": { "delete": { "operationId": "deleteDiffineryTokensById", "summary": "Revoke a token", "description": "Access: Any active account (a token, or a browser session). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Tokens and agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/sandboxes": { "post": { "operationId": "postReposByOwnerByRepoDiffinerySandboxes", "summary": "Start a sandbox", "description": "A container with the repository checked out, for agents to build and test in.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Sandboxes" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "description": "Branch, tag or commit to check out (default: the default branch)." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/sandboxes/{id}/{action}": { "post": { "operationId": "postReposByOwnerByRepoDiffinerySandboxesByIdByAction", "summary": "Use a sandbox", "description": "`action` is `exec` (run a command), `read` or `write` (files), or `close`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Sandboxes" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "action", "in": "path", "required": true, "description": "Action to take.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/accounts/{login}/actions-suspension": { "get": { "operationId": "getAdminAccountsByLoginActionsSuspension", "summary": "Get an account's Actions suspension", "description": "Site administrators only. `suspended`, `reason`, `suspended_by` and `suspended_at`.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putAdminAccountsByLoginActionsSuspension", "summary": "Suspend Actions for an account", "description": "Site administrators only. As for a repository, for every repository the person or organization owns; their running runs and sandboxes stop now. Audited as `actions.suspend`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why (up to 500 characters). Shown to the people affected and kept in the audit log." } }, "required": [ "reason" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAdminAccountsByLoginActionsSuspension", "summary": "Lift an account's Actions suspension", "description": "Site administrators only. New work can start again; nothing restarts. Audited as `actions.unsuspend`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/accounts/{login}/quotas": { "get": { "operationId": "getAdminAccountsByLoginQuotas", "summary": "Get an account's quotas and usage", "description": "Site administrators only.\n\nAccess: A site administrator. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchAdminAccountsByLoginQuotas", "summary": "Change an account's quotas", "description": "Site administrators only. Send only the quotas to change: a whole number, `-1` for unlimited, or `null` for the default. Audited as `account.quotas.set`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "login", "in": "path", "required": true, "description": "Account login.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "hosted_minutes": { "type": "integer", "description": "Hosted minutes per calendar month (UTC)." }, "hosted_jobs": { "type": "integer", "description": "Hosted Actions jobs running at once." }, "sandboxes": { "type": "integer", "description": "Agent sandboxes open at once." }, "repositories": { "type": "integer", "description": "Repositories the account owns." }, "storage_bytes": { "type": "integer", "description": "Bytes stored: git objects, Git LFS objects, release assets and packages, not Actions artifacts or caches." } }, "required": [] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/hosted-compute-pause": { "get": { "operationId": "getAdminHostedComputePause", "summary": "Get the hosted compute pause", "description": "Site administrators only. `paused`, `reason`, `paused_by` and `paused_at`.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putAdminHostedComputePause", "summary": "Pause hosted compute", "description": "Site administrators only. Hosted jobs fail without starting and sandboxes are refused everywhere; running ones stop now. Self-hosted runners still work. Audited as `compute.pause`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why (up to 500 characters). Shown to the people affected and kept in the audit log." } }, "required": [ "reason" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAdminHostedComputePause", "summary": "Resume hosted compute", "description": "Site administrators only. New hosted jobs and sandboxes can start again; nothing restarts. Audited as `compute.unpause`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/reports": { "get": { "operationId": "getAdminReports", "summary": "List reports", "description": "Site administrators only. Newest first, with the reporter, the account reported, the excerpt kept when it was reported and the resolution. The total is in `x-total-count`.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "`open` (default), `resolved` or `all`.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page (default 30, at most 100).", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/reports/{id}": { "get": { "operationId": "getAdminReportsById", "summary": "Get a report", "description": "Site administrators only.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchAdminReportsById", "summary": "Resolve or reopen a report", "description": "Site administrators only. Audited as `report.resolve` or `report.reopen`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`resolved` or `open`." }, "resolution": { "type": "string", "description": "What you did, for `resolved` (up to 2,000 characters)." } }, "required": [ "state" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/repos/{owner}/{repo}/actions-suspension": { "get": { "operationId": "getAdminReposByOwnerByRepoActionsSuspension", "summary": "Get a repository's Actions suspension", "description": "Site administrators only. `suspended`, `reason`, `suspended_by`, `suspended_at`, and `owner_suspended` when its owner's Actions are suspended.\n\nAccess: A site administrator. Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putAdminReposByOwnerByRepoActionsSuspension", "summary": "Suspend Actions for a repository", "description": "Site administrators only. No runs start, queued jobs fail and no sandboxes open; what runs now stops (`stopped`). Audited as `actions.suspend`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why (up to 500 characters). Shown to the people affected and kept in the audit log." } }, "required": [ "reason" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAdminReposByOwnerByRepoActionsSuspension", "summary": "Lift a repository's Actions suspension", "description": "Site administrators only. New work can start again; nothing restarts. Audited as `actions.unsuspend`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app": { "get": { "operationId": "getApp", "summary": "List app", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app/installations": { "get": { "operationId": "getAppInstallations", "summary": "List installations", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app/installations/{id}": { "get": { "operationId": "getAppInstallationsById", "summary": "Get a installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAppInstallationsById", "summary": "Delete a installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app/installations/{id}/access_tokens": { "post": { "operationId": "postAppInstallationsByIdAccessTokens", "summary": "Create a access token", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/app/installations/{id}/suspended": { "put": { "operationId": "putAppInstallationsByIdSuspended", "summary": "Set suspended", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAppInstallationsByIdSuspended", "summary": "Delete suspended", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/apps/{slug}": { "get": { "operationId": "getAppsBySlug", "summary": "Get a app", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/apps": { "get": { "operationId": "getDiffineryApps", "summary": "List apps", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDiffineryApps", "summary": "Create a app", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/apps/{slug}": { "get": { "operationId": "getDiffineryAppsBySlug", "summary": "Get a app", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchDiffineryAppsBySlug", "summary": "Update a app", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDiffineryAppsBySlug", "summary": "Delete a app", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/apps/{slug}/installations": { "post": { "operationId": "postDiffineryAppsBySlugInstallations", "summary": "Create a installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/apps/{slug}/keys": { "get": { "operationId": "getDiffineryAppsBySlugKeys", "summary": "List keys", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDiffineryAppsBySlugKeys", "summary": "Create a key", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/apps/{slug}/keys/{keyId}": { "delete": { "operationId": "deleteDiffineryAppsBySlugKeysByKeyId", "summary": "Delete a key", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "slug", "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "description": "keyId", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/auto-merge": { "get": { "operationId": "getDiffineryAutoMerge", "summary": "Your auto-merge setting", "description": "Whether Diffinery turns on auto-merge for the pull requests you open: `{ enabled, merge_method }`, where `merge_method` is `default` (as the branch merges), `merge`, `squash`, `rebase`, or null when off. An agent's token reads the agent's own. See /docs/collaboration/merge-on-green.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putDiffineryAutoMerge", "summary": "Turn auto-merge on or off for pull requests you open", "description": "People only. When on, Diffinery turns on auto-merge for you as you open a pull request (or mark your draft ready), wherever its base branch has at least one required check; it merges once every rule of the branch is met, approvals included. The body may also be just `true` or `false`. Returns the setting. Audited as `account.auto_merge`. See /docs/collaboration/merge-on-green.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "On or off." }, "merge_method": { "type": "string", "description": "`default` (as the branch merges, the default), `merge`, `squash` or `rebase`." } }, "required": [ "enabled" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/email": { "get": { "operationId": "getDiffineryEmail", "summary": "Your email address and whether it is suppressed", "description": "`suppressed` is null, or why Diffinery sends nothing to your address: `reason` (`hard-bounce`, `complaint` or `manual`), `detail`, `source`, `created_at` and `owner_can_lift`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/email/verification": { "post": { "operationId": "postDiffineryEmailVerification", "summary": "Ask for the email that turns email back on", "description": "When your address is suppressed by a bounce or complaint, sends one email to it, past the suppression list; following its link while signed in lifts the suppression. 409 when it isn't suppressed, 403 for a suppression a site administrator added, at most 3 an hour.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/installations/{id}": { "get": { "operationId": "getDiffineryInstallationsById", "summary": "Get a installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchDiffineryInstallationsById", "summary": "Update a installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDiffineryInstallationsById", "summary": "Delete a installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/installations/{id}/accept_permissions": { "post": { "operationId": "postDiffineryInstallationsByIdAcceptPermissions", "summary": "Create a accept permission", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/installations/{id}/suspended": { "put": { "operationId": "putDiffineryInstallationsByIdSuspended", "summary": "Set suspended", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDiffineryInstallationsByIdSuspended", "summary": "Delete suspended", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/model-keys": { "get": { "operationId": "getDiffineryModelKeys", "summary": "List your model keys", "description": "Your saved model API keys for agent tasks: `provider` (`anthropic`, `openai` or `openrouter`), `hint` (the key's last four characters), `opted_in_at`, `created_at` and `updated_at`. The keys themselves are never returned. See /docs/agents/tasks#model-access.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/model-keys/{provider}": { "put": { "operationId": "putDiffineryModelKeysByProvider", "summary": "Save a model key", "description": "From a browser session only: no token, agent, job or sandbox can set a model key. `provider` is `anthropic`, `openai` or `openrouter`. `accept_terms: true` records that you use that provider through Diffinery under your own account and its terms (422 without it). The key is encrypted, never shown again and never sent to a sandbox. Sends you a security email. Audited as `model_key.set`.\n\nAccess: Any active account (a token, or a browser session). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "provider", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The API key (`sk-ant-...`, `sk-...` or `sk-or-...`)." }, "accept_terms": { "type": "boolean", "description": "Must be `true`." } }, "required": [] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDiffineryModelKeysByProvider", "summary": "Delete a model key", "description": "From a browser session only. Running tasks that use it lose model access. Audited as `model_key.delete`.\n\nAccess: Any active account (a token, or a browser session). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "provider", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "none", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/model-usage": { "get": { "operationId": "getDiffineryModelUsage", "summary": "Get your model usage", "description": "The model usage you paid for over the last `days`, as on Settings → Model access: `days`, `since`, and `repositories`, one line per repository (named as it was when its runs ended) and `kind` (`task`, `review` or `coordinator`) with `runs`, `reported_by_cli_runs`, `requests`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens` and `cost_usd` (`null` when no run reported a cost). A token limited to some repositories sees only their lines. See /docs/agents/tasks#usage-and-cost.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "1 to 90 (default 30).", "schema": { "type": "integer" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/reports": { "post": { "operationId": "postDiffineryReports", "summary": "Report content to the site administrators", "description": "Diffinery only. People only, at most 20 a day and one open report per thing. Returns the report (`id`, `kind`, `target`, `html_url`, `reason`, `body`, `state`, `created_at`). Audited as `report.create`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "`user`, `repository`, `issue`, `pull_request` or `comment`." }, "login": { "type": "string", "description": "The person, for `user`." }, "repository": { "type": "string", "description": "`owner/name`, for everything but `user`." }, "number": { "type": "integer", "description": "The issue or pull request, for `issue` and `pull_request`." }, "comment_id": { "type": "string", "description": "The comment, for `comment`." }, "reason": { "type": "string", "description": "`spam`, `harassment`, `hate`, `violence`, `sexual`, `malware`, `impersonation` or `other`." }, "body": { "type": "string", "description": "A note for the administrators (up to 2,000 characters; required for `other`)." } }, "required": [ "kind", "reason" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/tasks": { "get": { "operationId": "getDiffineryTasks", "summary": "List your agent tasks", "description": "Agent tasks you started across repositories where you still have write access, most recently changed first (for an agent's token: the tasks it runs). A token limited to repositories sees only those.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diffinery/today": { "get": { "operationId": "getDiffineryToday", "summary": "Your morning view", "description": "Pull requests that need you, your agents' open pull requests with their state, and what merged, was released or failed in the last 24 hours, across the repositories you can see that were active in the last 30 days (at most 100). A token limited to repositories sees only those. See /docs/agents/today.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/installation/repositories": { "get": { "operationId": "getInstallationRepositories", "summary": "List repositories", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/installation/token": { "delete": { "operationId": "deleteInstallationToken", "summary": "Delete token", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/blocks": { "get": { "operationId": "getOrgsByOrgBlocks", "summary": "List the people an organization blocked", "description": "Organization owners and site administrators.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/blocks/{username}": { "get": { "operationId": "getOrgsByOrgBlocksByUsername", "summary": "Check whether an organization blocked a person", "description": "`204` if it did, `404` if not.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "read", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putOrgsByOrgBlocksByUsername", "summary": "Block a person from an organization", "description": "As blocking for yourself, for every repository the organization owns. Members can't be blocked. Audited as `org.block`.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrgBlocksByUsername", "summary": "Unblock a person from an organization", "description": "Audited as `org.unblock`.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/diffinery/agent-policy": { "get": { "operationId": "getOrgsByOrgDiffineryAgentPolicy", "summary": "Get an organization's agent policy", "description": "Owners only (and site administrators); a token limited to repositories gets 403. `keys` (`personal`, `either` or `organization`: whose key pays), `runtimes` (`claude-code`, `codex`, `custom`), `providers` (`anthropic`, `openai`, `openrouter`), `max_running` (tasks at once per repository, 1 to 10), `terminals`, `terminal_tasks`, `review`, `member_monthly_tokens` (`null` for no allowance), `updated_by` and `updated_at`. See /docs/agents/organizations.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putOrgsByOrgDiffineryAgentPolicy", "summary": "Change an organization's agent policy", "description": "From a browser session only, by an owner. Fields left out stay as they are; answers with the whole policy. 422 when a value is out of range, or no runtime or provider is left allowed. Each repository's tasks at once are held to `max_running` right away. Audited as `org.agent_policy.update`, with the new values.\n\nAccess: An owner of the organization (or a site admin). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "string", "description": "`personal` (each person's own keys), `either` (the organization's keys when it has them) or `organization` (only the organization's keys)." }, "runtimes": { "type": "array", "description": "Allowed runtimes: `claude-code`, `codex`, `custom`. At least one." }, "providers": { "type": "array", "description": "Allowed providers: `anthropic`, `openai`, `openrouter`. At least one." }, "max_running": { "type": "integer", "description": "Most tasks at once per repository, 1 to 10." }, "terminals": { "type": "boolean", "description": "Allow web terminals." }, "terminal_tasks": { "type": "boolean", "description": "Let terminals run agent tasks." }, "review": { "type": "boolean", "description": "Allow agent review." }, "member_monthly_tokens": { "type": "integer", "description": "Tokens one person may spend of the organization's keys in a calendar month (UTC), 10,000 to 10,000,000,000, or `null` for no allowance." } }, "required": [] } } } }, "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/diffinery/model-keys": { "get": { "operationId": "getOrgsByOrgDiffineryModelKeys", "summary": "List an organization's model keys", "description": "Owners only; a token limited to repositories gets 403. Each key as `GET /diffinery/model-keys` shows a personal one: `provider`, `hint` (last four characters), `opted_in_at`, `created_at` and `updated_at`. The keys themselves are never returned. See /docs/agents/organizations.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/diffinery/model-keys/{provider}": { "put": { "operationId": "putOrgsByOrgDiffineryModelKeysByProvider", "summary": "Save an organization's model key", "description": "From a browser session with a sign-in from the last 2 hours, by an owner. `provider` is `anthropic`, `openai` or `openrouter`; `accept_terms: true` is required. The key is encrypted, never shown again and never sent to a sandbox. Every owner gets a security email. Audited as `org.model_key.set`.\n\nAccess: An owner of the organization (or a site admin). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "provider", "in": "path", "required": true, "description": "provider", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The API key (`sk-ant-...`, `sk-...` or `sk-or-...`)." }, "accept_terms": { "type": "boolean", "description": "Must be `true`." } }, "required": [] } } } }, "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteOrgsByOrgDiffineryModelKeysByProvider", "summary": "Delete an organization's model key", "description": "From a browser session with a sign-in from the last 2 hours, by an owner. 404 when the organization has no key for that provider. Audited as `org.model_key.delete`.\n\nAccess: An owner of the organization (or a site admin). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "provider", "in": "path", "required": true, "description": "provider", "schema": { "type": "string" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "none", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/diffinery/model-usage": { "get": { "operationId": "getOrgsByOrgDiffineryModelUsage", "summary": "Get an organization's model usage", "description": "Owners only; a token limited to repositories gets 403. The runs the organization's keys paid for over the last `days`, shaped like `GET /diffinery/model-usage` with a `person` on each line, and `month`: `month`, `member_monthly_tokens` and `people` (each `person` and their `tokens` on the organization's keys this month). See /docs/agents/organizations#usage.\n\nAccess: An owner of the organization (or a site admin). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "1 to 90 (default 30).", "schema": { "type": "integer" } } ], "x-diffinery-access": "org-owner", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/installation": { "get": { "operationId": "getOrgsByOrgInstallation", "summary": "List installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org}/usage": { "get": { "operationId": "getOrgsByOrgUsage", "summary": "Get an organization's quotas and usage", "description": "The same as `GET /user/usage`, for the organization's owners and admins.\n\nAccess: An owner or admin of the organization (or a site admin). Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "org-admin", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/agent-review": { "get": { "operationId": "getReposByOwnerByRepoDiffineryAgentReview", "summary": "Get agent review settings", "description": "Whether agent review is on, which agent reviews with which runtime, whose model key every review uses (`uses_key_of`), when it reviews (`trigger`: `push`, `open` or `request`), which pull requests (`authors`: `all`, `people` or `agents`), `drafts`, `autofix`, `daily_limit` and `tokens_per_review`. `{\"enabled\": false}` when it was never turned on. Needs write access. See /docs/agents/review.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoDiffineryAgentReview", "summary": "Turn agent review on, change or off", "description": "From a browser session only, by a repository admin who can run tasks as the agent and has the runtime's model key: every review on the repository, including ones other people ask for, spends that admin's key, so `accept_terms` must be true. `{\"enabled\": false}` turns it off. Audited as `review.settings`.\n\nAccess: Admin access to the repository (or to the package). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "description": "The reviewing agent's login (required)." }, "runtime": { "type": "string", "description": "`claude-code` (default), `codex` or `custom`." }, "provider": { "type": "string", "description": "Where the runtime's model calls go: its own provider (`anthropic` for Claude Code, `openai` for Codex; the default) or `openrouter`." }, "model": { "type": "string", "description": "With `provider: openrouter`: the OpenRouter model id (default `~anthropic/claude-sonnet-latest` for Claude Code, `~openai/gpt-sol-latest` for Codex)." }, "command": { "type": "string", "description": "For `custom`: the shell command; it must end its output with the findings block the prompt describes." }, "trigger": { "type": "string", "description": "`push` (default: on open and every push), `open` (once per pull request) or `request` (only when asked)." }, "authors": { "type": "string", "description": "`all` (default), `people` or `agents`." }, "drafts": { "type": "boolean", "description": "Review drafts too (default false)." }, "autofix": { "type": "boolean", "description": "Start a fix task on the pull request's branch for blocking findings (default false; at most 3 times per pull request)." }, "daily_limit": { "type": "integer", "description": "Most reviews and autofix runs the repository starts in 24 hours, 1 to 1000 (default 50). Past it, pull requests get an action-required check, autofix waits, and you get an email." }, "tokens_per_review": { "type": "integer", "description": "Most tokens one review may use, counted from the provider's responses (cache reads count as a tenth), 100000 to 50000000 (default 2000000)." }, "accept_terms": { "type": "boolean", "description": "Must be true: reviews use your model key." }, "enabled": { "type": "boolean", "description": "`false` turns agent review off." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/agent-setup": { "get": { "operationId": "getReposByOwnerByRepoDiffineryAgentSetup", "summary": "Get the agent setup check", "description": "The latest Check on Settings → Agent setup, or `check: null` before any: `ok`, `checked_at`, `first_ok_at` (when a check first passed), the `account` and `token` (`name`, `prefix`) that reported it, `cli_version` and the `checks` lines. See [Cloud agent environments](/docs/connect/cloud-agents).\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/agent-setup/checks": { "post": { "operationId": "postReposByOwnerByRepoDiffineryAgentSetupChecks", "summary": "Report an agent setup check", "description": "What the hosted setup script (`/{owner}/{repo}/agent-setup.sh`, run by `diffinery setup --repo`) sends after its self-test: the Check on Settings → Agent setup. Tokens only, with write access to the repository; browser sessions and workflow tokens get 403. The report is green only when every line passed. Returns `ok` and the page's `html_url`. See [Cloud agent environments](/docs/connect/cloud-agents).\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object" }, "description": "1 to 30 lines of `{ name, ok, message }`: what was checked, whether it passed, and what to change when it didn't." }, "cli_version": { "type": "string", "description": "The CLI's version." } }, "required": [ "checks" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/comments/{id}/minimized": { "put": { "operationId": "putReposByOwnerByRepoDiffineryCommentsByIdMinimized", "summary": "Hide (minimize) a comment", "description": "Diffinery only (GitHub's GraphQL `minimizeComment`). Write access, people only. The comment is shown collapsed with its reason. Audited as `comment.minimize`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "`spam`, `abuse`, `off_topic`, `outdated`, `duplicate` or `resolved` (or GitHub's `classifier`, such as `OFF_TOPIC`)." } }, "required": [ "reason" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoDiffineryCommentsByIdMinimized", "summary": "Show a hidden comment again", "description": "Diffinery only. Write access, people only. Audited as `comment.unminimize`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/delete-closed-pulls": { "post": { "operationId": "postReposByOwnerByRepoDiffineryDeleteClosedPulls", "summary": "Delete closed pull requests", "description": "For starting over with fresh history after rewriting the branches. Permanently deletes every closed and merged pull request (not ones still in the merge queue) with its comments, reviews, review comments, timeline events, reactions and `refs/pull/{number}/*` refs, then purges unreachable objects as `POST .../diffinery/purge-unreachable` does. Issues, open pull requests, branches, tags and workflow runs stay; pull request numbers are not reused. Returns `{ pull_requests, objects, bytes }`. People only, not agents. Repositories of up to 300,000 objects (422 otherwise). From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL. Audited as `repo.delete_closed_pulls`. See /docs/repositories/overview#start-over-with-fresh-history.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project": { "get": { "operationId": "getReposByOwnerByRepoDiffineryProject", "summary": "Get the project", "description": "The repository's project: `settings` (`max_running`, `instructions`, `plan_first`), `memory` (`body`, `version`, `updated_by`, `updated_at`) and `board`, the agent tasks by column (`waiting`, `working`, `queued`, `review`, `landing`, `done`, `idle`). Agent reviews aren't on the board. Needs write access. See /docs/agents/projects.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project/coordinator": { "get": { "operationId": "getReposByOwnerByRepoDiffineryProjectCoordinator", "summary": "Get your coordinator", "description": "Your coordinator's settings in this project: `enabled`, `agent`, `runtime`, `command`, `provider`, `model`, `tokens_per_run`, `tokens_per_task`, `opted_in_at`, `updated_at`. Needs write access.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoDiffineryProjectCoordinator", "summary": "Turn on or change your coordinator", "description": "Your agent then reads your posts and turns them into tasks, on your model key. Each coordinator starts at most 5 tasks per post and 20 per 24 hours in the project. A person in a browser session only. Audited as `project.coordinator`. See /docs/agents/projects#coordinator.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string", "description": "The login of an agent you manage with write access to the repository." }, "runtime": { "type": "string", "description": "`claude-code` (default), `codex` or `custom`." }, "command": { "type": "string", "description": "For `custom`: the shell command." }, "provider": { "type": "string", "description": "`openrouter` to run Claude Code or Codex via OpenRouter." }, "model": { "type": "string", "description": "With `provider: openrouter`: the OpenRouter model id." }, "tokens_per_run": { "type": "integer", "description": "Token budget of each coordinator run, 100,000 to 50,000,000 (default 1,000,000)." }, "tokens_per_task": { "type": "integer", "description": "Token budget of each run of a task it starts, 100,000 to 50,000,000 (default 2,000,000)." }, "accept": { "type": "boolean", "description": "Must be `true`: confirms your coordinator and its tasks use your model key." } }, "required": [ "agent", "accept" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteReposByOwnerByRepoDiffineryProjectCoordinator", "summary": "Turn off your coordinator", "description": "A person in a browser session only. Audited as `project.coordinator`.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project/coordinators": { "get": { "operationId": "getReposByOwnerByRepoDiffineryProjectCoordinators", "summary": "List the coordinators in a project", "description": "Every person's coordinator in this project, oldest first: `person`, `agent`, `runtime`, `provider`, `model`, `opted_in_at`. Never their token budgets or custom command. Needs write access. See /docs/agents/projects#coordinator.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project/memory": { "get": { "operationId": "getReposByOwnerByRepoDiffineryProjectMemory", "summary": "Get the project memory", "description": "The current memory and its last 50 `versions` (`version`, `updated_by`, `updated_at`, `length`). Every agent task reads it as background notes; agent reviews don't. Needs write access.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putReposByOwnerByRepoDiffineryProjectMemory", "summary": "Save or restore the project memory", "description": "Saves `body` (at most 40,000 characters) as a new version, or restores an earlier version as a new one with `restore` (404 `no such memory version`). A person in a browser session only. Audited as `project.memory`.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The new memory (Markdown)." }, "restore": { "type": "integer", "description": "A version number to restore instead." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project/posts": { "get": { "operationId": "getReposByOwnerByRepoDiffineryProjectPosts", "summary": "List the project conversation", "description": "Posts and task events, oldest first: those after `after`, or the latest 100. Needs write access.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Return posts after this id (default 0).", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "At most 100 (default 100).", "schema": { "type": "integer" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoDiffineryProjectPosts", "summary": "Post to the project conversation", "description": "Markdown, at most 20,000 characters (422 otherwise). If you have a coordinator in this project, it handles the post unless you send `coordinator: false`; the response's `coordinator` says whether it did. A person in a browser session only. 403 on an archived repository.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The post." }, "coordinator": { "type": "boolean", "description": "`false` to post without handing it to your coordinator." } }, "required": [ "body" ] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project/posts/{n}/handle": { "post": { "operationId": "postReposByOwnerByRepoDiffineryProjectPostsByNHandle", "summary": "Hand a post to your coordinator", "description": "Your coordinator handles post `n`, anyone's, on your model key. Each post is handled once. A person in a browser session only. Audited as `project.coordinate`. See /docs/agents/projects#coordinator.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "n", "in": "path", "required": true, "description": "n", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/project/settings": { "put": { "operationId": "putReposByOwnerByRepoDiffineryProjectSettings", "summary": "Change the project settings", "description": "Project instructions every agent task and agent review gets, how many tasks run at once, and whether tasks plan first. Tasks beyond `max_running` queue and start oldest first. A person in a browser session only. Audited as `project.settings`.\n\nAccess: Admin access to the repository (or to the package). No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_running": { "type": "integer", "description": "1 to 10 (default 3)." }, "instructions": { "type": "string", "description": "At most 10,000 characters." }, "plan_first": { "type": "string", "description": "`off` (default: tasks build at once unless started with `plan_first: true`), `default` (tasks plan first unless started with `plan_first: false`) or `required` (every task plans first, including ones coordinators start)." } }, "required": [] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/purge-unreachable": { "post": { "operationId": "postReposByOwnerByRepoDiffineryPurgeUnreachable", "summary": "Purge unreachable objects", "description": "Permanently deletes every commit, tree and file that no branch, tag, pull request, merge queue entry or unfinished workflow run reaches, and empties the archive cache, so a secret force-pushed away can't be fetched by its SHA. Returns `{ objects, bytes }`. People only, not agents. Repositories of up to 300,000 objects (422 otherwise). From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL. Audited as `repo.purge_unreachable`. See /docs/security/push-protection#removing-a-secret-that-was-pushed.\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks": { "get": { "operationId": "getReposByOwnerByRepoDiffineryTasks", "summary": "List agent tasks", "description": "The repository's agent tasks, newest first. Needs write access: transcripts show an agent's reasoning and command output. `state` filters: `queued`, `running`, `ready`, `failed` or `stopped`, or `active` for running and queued together.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "`queued`, `running`, `ready`, `failed`, `stopped` or `active` (running or queued).", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "At most 100 (default 50).", "schema": { "type": "integer" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postReposByOwnerByRepoDiffineryTasks", "summary": "Start an agent task", "description": "From a browser session only, by a person with write access, as one of their agents (they own it, or administer the organization that owns it) that has write access here: each run spends the person's own model key, so no token can start one. The agent works in a sandbox, then Diffinery pushes `agent/-` and opens a pull request as the agent. 422 when the runtime needs a model key you haven't saved. Audited as `task.start`. See /docs/agents/tasks.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string", "description": "What to do (required, at most 20,000 characters)." }, "runtime": { "type": "string", "description": "`claude-code` (default), `codex` or `custom`." }, "provider": { "type": "string", "description": "Where the runtime's model calls go: its own provider (`anthropic` for Claude Code, `openai` for Codex; the default) or `openrouter`." }, "model": { "type": "string", "description": "With `provider: openrouter`: the OpenRouter model id (default `~anthropic/claude-sonnet-latest` for Claude Code, `~openai/gpt-sol-latest` for Codex)." }, "agent": { "type": "string", "description": "The agent's login (required)." }, "base": { "type": "string", "description": "Branch to start from (default: the default branch)." }, "plan_first": { "type": "boolean", "description": "`true` to plan in a read-only sandbox before building, `false` to build at once. Left out, the project's default; a project that requires plans ignores `false`. See /docs/agents/tasks#plan-first." }, "attempts": { "type": "integer", "description": "1 (default) to 4: run the first build as that many attempts side by side, then pick one (422 above 1 for a task on a pull request's branch). See /docs/agents/tasks#best-of-n." }, "fix_checks": { "type": "boolean", "description": "Start a fix run when the pull request's checks fail (default `true`, `false` for a task on a pull request's branch). See /docs/agents/tasks#verify-and-land." }, "land": { "type": "boolean", "description": "Turn on auto-merge for its pull request as the task's agent, so it merges once approved and checks pass (default `false`)." }, "command": { "type": "string", "description": "For `custom`: the shell command to run." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}": { "get": { "operationId": "getReposByOwnerByRepoDiffineryTasksByNumber", "summary": "Get an agent task", "description": "The task, its runs and its pull request. Needs write access. A plan-first task also has `plan_state` (`planning`, `waiting`, `approved` or `split`) and `plan`; a task split from a plan has `parent_task`. A task with more than one attempt has `pick_state` (`running`, `waiting` or `picked`) and `picked_attempt`, and each run its `attempt`. Every task has `fix_checks`, `check_fixes` (fix runs started so far) and `land`, `paid_by` (`person`, or `organization` when an organization's key pays), and `usage` (the model usage of all its runs; each run has its own `usage`, with `source`: `proxy`, or `runtime` for a run in a terminal). See /docs/agents/tasks#usage-and-cost.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchReposByOwnerByRepoDiffineryTasksByNumber", "summary": "Change a task's options", "description": "From a browser session only, by the person who started the task. `fix_checks` starts a fix run when its pull request's checks fail (one per commit, at most 3 per task); turning `land` on turns on auto-merge for an open pull request as the task's agent, under the usual rules for agents. 422 when a value isn't `true` or `false`; 409 `only agent tasks have these options` for an agent review. Audited as `task.options`. See /docs/agents/tasks#verify-and-land.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fix_checks": { "type": "boolean", "description": "Fix failing checks." }, "land": { "type": "boolean", "description": "Land when approved." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/attempts": { "get": { "operationId": "getReposByOwnerByRepoDiffineryTasksByNumberAttempts", "summary": "Compare a task's attempts", "description": "Needs write access. One entry per attempt of a best-of-N task: `attempt`, `run`, `state`, `error`, `branch`, `head_sha`, `changes` (`files`, `additions`, `deletions`), `checks` and `failing_checks` on its branch, `model_requests`, `tokens`, `summary` (its last message) and `compare_url`. See /docs/agents/tasks#best-of-n.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/attempts/{attempt}/pick": { "post": { "operationId": "postReposByOwnerByRepoDiffineryTasksByNumberAttemptsByAttemptPick", "summary": "Pick a task's attempt", "description": "From a browser session only, by the person who started the task. The attempt's branch becomes the task's branch, with a pull request; the other attempts' branches are deleted. 409 `the attempts are still running`, `attempt is already picked` or `this task has no attempts to pick from`; 404 `no such attempt`; 422 `attempt has no work to pick: ...` when it changed nothing or didn't finish. Audited as `task.pick`.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "attempt", "in": "path", "required": true, "description": "attempt", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/messages": { "post": { "operationId": "postReposByOwnerByRepoDiffineryTasksByNumberMessages", "summary": "Send a task a follow-up", "description": "From a browser session only, by the person who started the task. Starts a new run on the task's branch with the message (while a run is active, it waits and starts when that run ends). Audited as `task.message`.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The message." } }, "required": [] } } } }, "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/plan/approve": { "post": { "operationId": "postReposByOwnerByRepoDiffineryTasksByNumberPlanApprove", "summary": "Approve a task's plan", "description": "From a browser session only, by the person who started the task. The build run starts with the goal and the plan, and every later run gets the plan as the approved one. 409 `the plan isn't ready yet` while it plans, `this task has no plan waiting for approval`, or `the task is running`. Audited as `task.plan_approve`. See /docs/agents/tasks#plan-first.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/plan/split": { "post": { "operationId": "postReposByOwnerByRepoDiffineryTasksByNumberPlanSplit", "summary": "Split a task's plan into tasks", "description": "From a browser session only, by the person who started the task. Your coordinator gets the goal and the plan as a post of yours and starts tasks for its parts, each with `parent_task`; this task is then done with. Returns `post`, `task` (the coordinator's run) and `status` (`started` or `queued`). 422 `set up your coordinator for this project first` without a coordinator; the same 409s as approving. Audited as `task.plan_split`.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/retry": { "post": { "operationId": "postReposByOwnerByRepoDiffineryTasksByNumberRetry", "summary": "Retry a task", "description": "From a browser session only, by the person who started the task, when no run is active (409 otherwise). Audited as `task.retry`.\n\nAccess: Write access to the repository. No token can call it: it needs a browser session.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "none", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/stop": { "post": { "operationId": "postReposByOwnerByRepoDiffineryTasksByNumberStop", "summary": "Stop a task", "description": "The person who started it, its agent, or a repository admin. Stops the agent, closes the sandbox (its git credential stops working) and ends the run's model access. Work already pushed stays. Audited as `task.stop`.\n\nAccess: Write access to the repository. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/diffinery/tasks/{number}/transcript": { "get": { "operationId": "getReposByOwnerByRepoDiffineryTasksByNumberTranscript", "summary": "Read a task's transcript", "description": "Lines after `after` (a line number), oldest first: `stream` is `out` and `err` (the runtime's output, Claude Code's `stream-json` or Codex's `--json` lines), `setup` (installing and pushing) or `note` (Diffinery's own). Model keys and git credentials are masked.\n\nAccess: Write access to the repository. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Issue or pull request number.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Return lines after this one.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "At most 5000 (default 2000).", "schema": { "type": "integer" } } ], "x-diffinery-access": "write", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/installation": { "get": { "operationId": "getReposByOwnerByRepoInstallation", "summary": "List installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repos/{owner}/{repo}/transfer": { "post": { "operationId": "postReposByOwnerByRepoTransfer", "summary": "Transfer a repository", "description": "Moves the repository to `new_owner`: the caller's own account, or an organization where the caller is an owner or admin. Needs admin access to the repository (a personal repository: its owner) and a token with the admin scope; agents, job tokens (`GITHUB_TOKEN`) and sandbox tokens are refused. 422 when the new owner already has a repository (or a container image of a moved image's name) with that name. Git data, issues, pull requests, Actions runs, secrets, variables, environments, webhooks and caches move with it, and so do container images linked to it. Direct collaborators keep their access; grants that came from the old organization (its members, their agents, its agents) are dropped, and the new owner's organization secrets and variables apply. The old owner/name keeps working for anyone who can read the repository, as on GitHub: API calls get a 301 (reads) or 307 (anything else) to the new URL, web pages a 301, Git (with a `This repository moved` notice on push) and MCP are served under the old name, and image names resolve to the moved images. Creating a repository at the old name ends the redirect. Admins of both owners get an email. Audited as `repo.transfer`. Returns the repository. From a browser session whose sign-in is more than 2 hours old: 403 `Confirm it's you: sign in with your passkey again to do this.` with a `confirm` URL (see /docs/security/overview#confirming-its-you).\n\nAccess: Admin access to the repository (or to the package). Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "owner", "in": "path", "required": true, "description": "Account (user or organization) that owns the repository or package.", "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "description": "Repository name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_owner": { "type": "string", "description": "Login of the user or organization to transfer to." }, "new_name": { "type": "string", "description": "A new name for the repository (default: keep its name)." } }, "required": [ "new_owner" ] } } } }, "x-diffinery-access": "admin", "x-diffinery-token-scope": "admin", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/blocks": { "get": { "operationId": "getUserBlocks", "summary": "List the people you blocked", "description": "People only. See [Blocking and reporting](/docs/accounts/blocking-and-reporting).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/blocks/{username}": { "get": { "operationId": "getUserBlocksByUsername", "summary": "Check whether you blocked a person", "description": "`204` if you did, `404` if not.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "putUserBlocksByUsername", "summary": "Block a person", "description": "In your repositories they (and their agents) can't open issues or pull requests, comment, review or react; they stop being a collaborator, pending invitations between you are cancelled and you get no notifications from them. Audited as `user.block`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUserBlocksByUsername", "summary": "Unblock a person", "description": "Audited as `user.unblock`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/installations": { "get": { "operationId": "getUserInstallations", "summary": "List installations", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/installations/{id}/repositories": { "get": { "operationId": "getUserInstallationsByIdRepositories", "summary": "List repositories", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/installations/{id}/repositories/{repoId}": { "put": { "operationId": "putUserInstallationsByIdRepositoriesByRepoId", "summary": "Set a repository", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "repoId", "in": "path", "required": true, "description": "repoId", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUserInstallationsByIdRepositoriesByRepoId", "summary": "Delete a repository", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `write` scope.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } }, { "name": "repoId", "in": "path", "required": true, "description": "repoId", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/memberships/orgs": { "get": { "operationId": "getUserMembershipsOrgs", "summary": "List your organization memberships", "description": "Active memberships and pending invitations, each with `state` (`active` or `pending`), `role` (GitHub's `admin` or `member`) and `diffinery_role` (`owner`, `admin` or `member`).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "`active` or `pending`.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/memberships/orgs/{org}": { "get": { "operationId": "getUserMembershipsOrgsByOrg", "summary": "Get your organization membership", "description": "404 when you are neither a member nor invited.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchUserMembershipsOrgsByOrg", "summary": "Accept an organization invitation", "description": "Send `{\"state\": \"active\"}` to join with the role the invitation offers. Audited as `invite.accept`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "org", "in": "path", "required": true, "description": "Organization login.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "`active`." } }, "required": [ "state" ] } } } }, "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/repository_invitations": { "get": { "operationId": "getUserRepositoryInvitations", "summary": "List your repository invitations", "description": "Pending invitations to repositories, sent to your username or your email address.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope and access to all repositories.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/repository_invitations/{id}": { "patch": { "operationId": "patchUserRepositoryInvitationsById", "summary": "Accept a repository invitation", "description": "You get the role it offers. Audited as `invite.accept`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUserRepositoryInvitationsById", "summary": "Decline a repository invitation", "description": "The invitation is deleted; nobody is told. Audited as `invite.decline`.\n\nAccess: Any active account (a token, or a browser session). Tokens need the `write` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier.", "schema": { "type": "string" } } ], "x-diffinery-access": "account", "x-diffinery-token-scope": "write", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/usage": { "get": { "operationId": "getUserUsage", "summary": "Get your quotas and usage", "description": "Hosted minutes used this month, hosted jobs running, sandboxes open, repositories owned and bytes stored, each with its `limit` (`-1` is unlimited), and `exempt` for accounts run by a site administrator. An agent gets its owner's. See [Limits](/docs/reference/limits#account-quotas).\n\nAccess: Any active account (a token, or a browser session). Tokens need the `read` scope.", "tags": [ "Other" ], "x-diffinery-access": "account", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{username}/installation": { "get": { "operationId": "getUsersByUsernameInstallation", "summary": "List installation", "description": "Access: Read access to the repository. Public repositories allow anyone to read. Tokens need the `read` scope.", "tags": [ "Other" ], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "read", "x-diffinery-token-scope": "read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/{username}/suspended": { "put": { "operationId": "putUsersByUsernameSuspended", "summary": "Suspend a person", "description": "Site administrators only (GitHub Enterprise's endpoint). Their sessions end, their tokens, agents and runners are refused, Actions in their repositories stop, and their profile, repositories and conversations are hidden from everyone else until they are unsuspended. Audited as `user.suspend`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why (up to 500 characters). Emailed to them and kept in the audit log." } }, "required": [ "reason" ] } } } }, "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteUsersByUsernameSuspended", "summary": "Unsuspend a person", "description": "Site administrators only. Everything comes back, tokens included. Audited as `user.unsuspend`.\n\nAccess: A site administrator. Tokens need the `admin` scope and access to all repositories.", "tags": [ "Other" ], "parameters": [ { "name": "username", "in": "path", "required": true, "description": "username", "schema": { "type": "string" } } ], "x-diffinery-access": "site-admin", "x-diffinery-token-scope": "admin", "responses": { "204": { "description": "No content" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "token": { "type": "http", "scheme": "bearer", "description": "A Diffinery personal access token (`dfy_...`) from Settings → Access tokens. `Authorization: token dfy_...` and HTTP Basic (token as the password) also work." } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }