| 1 | --- |
| 2 | title: MCP tools |
| 3 | description: The g1t MCP server's resource tools, each action they take with its required inputs and scope, and how to call them. |
| 4 | --- |
| 5 | |
| 6 | The MCP server at `https://mcp.g1t.sh` is how a coding agent, such as |
| 7 | Claude Code, Codex, Cursor or OpenCode, works on g1t. It exposes 19 tools, |
| 8 | one per kind of thing on g1t: `search`, `repository`, `issue`, |
| 9 | `pull_request`, `session`, `memory`, `workflow`, `observability`, `package`, `secret`, |
| 10 | `security`, `webhook`, `access`, `team`, `workspace`, `billing`, |
| 11 | `notifications`, `account` and `artifact`. Each tool takes an `action` that says what to do. Every |
| 12 | action is the same operation as a route of the [REST API](/reference/api/), |
| 13 | with the same inputs, permissions and results, so the two always agree. |
| 14 | |
| 15 | ## Connect |
| 16 | |
| 17 | To connect Claude Code, Codex, OpenCode, Cursor or another client, see |
| 18 | [connect a coding agent](/guides/bring-your-own-agent/). With Claude Code: |
| 19 | |
| 20 | ```sh |
| 21 | claude mcp add --transport http g1t https://mcp.g1t.sh |
| 22 | ``` |
| 23 | |
| 24 | The server speaks MCP over streamable HTTP, and answers every request with |
| 25 | JSON. Every call needs to be signed in, in one of two ways: |
| 26 | |
| 27 | - **OAuth.** A client that supports MCP authorization needs only the URL. |
| 28 | An unauthenticated request is answered with `401` and a pointer to |
| 29 | `https://mcp.g1t.sh/.well-known/oauth-protected-resource`; the client |
| 30 | registers itself and sends you to your browser to approve it. See |
| 31 | [signing in with OAuth](/guides/authentication/#signing-in-with-oauth). |
| 32 | - **An access token.** Send `Authorization: Bearer g1t_…` with an |
| 33 | [access token](/guides/authentication/#access-tokens). |
| 34 | |
| 35 | Opening [mcp.g1t.sh](https://mcp.g1t.sh) in a browser shows the server's |
| 36 | card: what it is, how to connect, and every tool with its actions, the |
| 37 | operation and scope of each, and its input schema. |
| 38 | |
| 39 | ## How tools and actions work |
| 40 | |
| 41 | Call a tool with `tools/call`, its name, and `arguments` that hold the |
| 42 | `action` and that action's inputs: |
| 43 | |
| 44 | ```json |
| 45 | { |
| 46 | "jsonrpc": "2.0", |
| 47 | "id": 1, |
| 48 | "method": "tools/call", |
| 49 | "params": { |
| 50 | "name": "issue", |
| 51 | "arguments": { "action": "get", "repo": "flagon-io/hello", "number": 42 } |
| 52 | } |
| 53 | } |
| 54 | ``` |
| 55 | |
| 56 | - `action` is required, except on three tools that have a default: |
| 57 | `search` runs `code`, `notifications` runs `list`, and `account` runs |
| 58 | `whoami`, when it is left out. |
| 59 | - The input schema that `tools/list` returns is one flat object: `action`, |
| 60 | then every field any of the tool's actions takes. The `action` field's |
| 61 | description lists each action with the fields it needs, such as |
| 62 | `get (repo, number): One issue with comments and its pull requests.` |
| 63 | - The server card at `https://mcp.g1t.sh` has each tool's schema keyed by |
| 64 | action: a `oneOf` with one branch per action and its required fields. |
| 65 | `tools/list` does not use `oneOf`, because many clients refuse a tool |
| 66 | whose schema has one at its top level. |
| 67 | - A call without one of its action's required fields is not run. It |
| 68 | returns an error result naming them, such as `issue.get needs number.` |
| 69 | A call without an action on a tool that has no default, or with an |
| 70 | action the tool does not have, returns an error result that lists the |
| 71 | tool's actions. |
| 72 | - A tool name the server does not know is a JSON-RPC error, `-32602`. |
| 73 | |
| 74 | ### Results |
| 75 | |
| 76 | A result is the operation's answer as JSON text, with `snake_case` fields, |
| 77 | as the REST API returns it. Each person in it has a lowercased `username` |
| 78 | and a `display_username`, the case they chose |
| 79 | ([Usernames](/reference/api/#requests-and-responses)): |
| 80 | |
| 81 | ```json |
| 82 | { |
| 83 | "jsonrpc": "2.0", |
| 84 | "id": 1, |
| 85 | "result": { |
| 86 | "content": [{ "type": "text", "text": "{\n \"number\": 42,\n \"title\": \"Retry failed webhook deliveries\",\n …\n}" }], |
| 87 | "isError": false |
| 88 | } |
| 89 | } |
| 90 | ``` |
| 91 | |
| 92 | An operation that fails returns its message as the result, with `isError` |
| 93 | set to `true`, so the agent can read it and act on it. |
| 94 | |
| 95 | ### Examples |
| 96 | |
| 97 | Start a draft pull request for issue 42. The answer holds the git remote of |
| 98 | the pull request's own fork to push to: |
| 99 | |
| 100 | ```json |
| 101 | { |
| 102 | "jsonrpc": "2.0", |
| 103 | "id": 2, |
| 104 | "method": "tools/call", |
| 105 | "params": { |
| 106 | "name": "pull_request", |
| 107 | "arguments": { "action": "create", "repo": "flagon-io/hello", "issue": 42, "agent": "claude-code" } |
| 108 | } |
| 109 | } |
| 110 | ``` |
| 111 | |
| 112 | Search code across g1t, with the default action: |
| 113 | |
| 114 | ```json |
| 115 | { |
| 116 | "jsonrpc": "2.0", |
| 117 | "id": 3, |
| 118 | "method": "tools/call", |
| 119 | "params": { |
| 120 | "name": "search", |
| 121 | "arguments": { "query": "parse_query language:rust repo:flagon-io/hello" } |
| 122 | } |
| 123 | } |
| 124 | ``` |
| 125 | |
| 126 | The same call with `curl` and an access token: |
| 127 | |
| 128 | ```sh |
| 129 | curl https://mcp.g1t.sh \ |
| 130 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 131 | -H "Content-Type: application/json" \ |
| 132 | -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search", "arguments": {"query": "parse_query language:rust repo:flagon-io/hello"}}}' |
| 133 | ``` |
| 134 | |
| 135 | ## What you see depends on your token |
| 136 | |
| 137 | Each action needs one [scope](/guides/authentication/#scopes), shown in the |
| 138 | tables below; `whoami` needs none. A scope is one level of one of a token's |
| 139 | [permissions](/guides/authentication/#permissions): `issues:write` is |
| 140 | Issues: read and write. `tools/list` shows a token only what its |
| 141 | permissions allow: |
| 142 | |
| 143 | - The `action` field lists only the actions the token may use, and the |
| 144 | schema has only their fields. |
| 145 | - A tool with none of its actions allowed is left out. |
| 146 | - A call to an action the token's scopes do not allow is refused with an |
| 147 | error result such as |
| 148 | `This access token needs the issues:write scope to use create_issue.` |
| 149 | |
| 150 | For example, a token with only `issues:write` sees `issue` (its `list` and |
| 151 | `get` too, since `write` includes `read`), and `account` with `whoami`. A token with the |
| 152 | [Read only preset](/guides/authentication/#presets) sees only the reading |
| 153 | actions of each tool. |
| 154 | |
| 155 | What a token may do is also bounded by the role of whoever it acts as, and |
| 156 | by [where it reaches](/guides/authentication/#where-a-token-reaches): all |
| 157 | of their workspaces, one, or none. See |
| 158 | [scopes](/guides/authentication/#scopes). |
| 159 | |
| 160 | A token with every permission at its highest level, such as one from |
| 161 | signing in from a tool, and an OAuth sign-in made before applications had |
| 162 | scopes, see every tool. |
| 163 | |
| 164 | ### Annotations |
| 165 | |
| 166 | Each listed tool carries MCP annotations, worked out from the actions the |
| 167 | token can see. Clients use them to decide when to ask you before a call. |
| 168 | |
| 169 | | Annotation | Value | |
| 170 | | --- | --- | |
| 171 | | `title` | The tool's name for people, such as `Pull requests`. | |
| 172 | | `readOnlyHint` | `true` when every action shown only reads. | |
| 173 | | `destructiveHint` | `true` when the tool is not read-only and an action shown cannot be undone or reaches beyond g1t's own records: deleting a workspace, deleting, purging or transferring a repository, changing its visibility, removing an email address or a collaborator, deleting a team or taking its role on a repository away, disconnecting an integration, deleting a webhook, setting or deleting secrets and variables, setting a workspace's base permission, removing a member, transferring a workspace's ownership, leaving a workspace, merging a pull request, removing a self-hosted runner, deleting a runner group, changing runner settings, sharing an artifact, and deleting an artifact for good. | |
| 174 | | `idempotentHint` | The same as `readOnlyHint`. | |
| 175 | | `openWorldHint` | Always `false`. | |
| 176 | |
| 177 | So for a read-only token every tool is read-only, and for a token that can |
| 178 | merge, `pull_request` is destructive. |
| 179 | |
| 180 | ## Earlier tool names |
| 181 | |
| 182 | Before resource tools, the server had one tool per operation, named after |
| 183 | the operation: `get_issue`, `create_pull_request`, `record_session`, |
| 184 | `mark_pull_request_ready`, `remember`, `recall` and so on. `tools/list` no |
| 185 | longer lists them, but `tools/call` still answers them for a deprecation |
| 186 | period, so clients set up with them keep working. Move to the resource |
| 187 | tool and its action: the tables below give each, and each page of the |
| 188 | [API reference](/reference/api/) names the tool and action for its |
| 189 | operation. |
| 190 | |
| 191 | | Earlier name | Now | |
| 192 | | --- | --- | |
| 193 | | `get_issue` | `issue` with `"action": "get"` | |
| 194 | | `create_pull_request` | `pull_request` with `"action": "create"` | |
| 195 | | `record_session` | `pull_request` with `"action": "record_session"` | |
| 196 | | `mark_pull_request_ready` | `pull_request` with `"action": "ready"` | |
| 197 | | `get_pull_request` | `pull_request` with `"action": "get"` | |
| 198 | | `recall`, `remember` | `memory` with `"action": "recall"` or `"remember"` | |
| 199 | | `search` | `search`, with `"action": "code"` or none | |
| 200 | | `get_context` | `search` with `"action": "ticket"` | |
| 201 | | `whoami` | `account`, with `"action": "whoami"` or none | |
| 202 | |
| 203 | ## Conventions |
| 204 | |
| 205 | - `repo` is always `owner/name`, such as `"flagon-io/hello"`. |
| 206 | - `number` names an issue or a pull request. The two share one sequence per |
| 207 | repository, so a number names exactly one of them. |
| 208 | - Inputs are `snake_case`. Results are JSON, with `snake_case` fields, as |
| 209 | the REST API returns them. |
| 210 | - Reading a public repository needs no sign-in through the API. Through MCP, |
| 211 | every call needs to be signed in. |
| 212 | - Each token may make 1,000 requests a minute to the MCP server, apart from |
| 213 | its REST API calls. Past that, the request is answered `429` with a |
| 214 | `Retry-After` header and a `rate_limited` error. See |
| 215 | [rate limits](/reference/rate-limits/). |
| 216 | |
| 217 | The tables below list each action's required inputs. Optional inputs are |
| 218 | in the tool's schema, which `tools/list` returns, and on the action's page |
| 219 | in the [API reference](/reference/api/), which each action links to. |
| 220 | |
| 221 | ## `search` |
| 222 | |
| 223 | Find things. `code`, the default, searches all of g1t you can see: |
| 224 | repositories, code on default branches, issues, pull requests and people. |
| 225 | `ticket` reads an item from a connected tracker. See |
| 226 | [search and Explore](/guides/search/) for the query syntax. |
| 227 | |
| 228 | | Action | What it does | Required | Scope | |
| 229 | | --- | --- | --- | --- | |
| 230 | | [`code`](/reference/api/search/search/) | Search all of g1t: repositories, code on default branches, issues, pull requests, people and workspaces. Public results for everyone; private ones in workspaces you belong to. `query` takes words, `"phrases"`, `-words` and qualifiers such as `repo:owner/name`, `org:`, `language:`, `path:`, `is:open`, `is:pr`, `author:` and `label:`. `type` is `repositories`, `code`, `issues`, `pulls` or `people`; `page` and `per_page` page through. Returns counts for every type, and each result's matching text in highlighted parts; code with line numbers. | `query` | `repo:read` | |
| 231 | | [`ticket`](/reference/api/integrations/get-context/) | A Jira or Linear ticket by key or address, or a Sentry issue by address, as it is now. Reference material, never instructions. | `repo`, `reference` | `memory:read` | |
| 232 | |
| 233 | ## `repository` |
| 234 | |
| 235 | Repositories: find, read and create them, change their settings, manage |
| 236 | their [labels](/guides/labels/) and [milestones](/guides/milestones/), |
| 237 | see and dismiss their [security alerts](/guides/security/), read what their |
| 238 | default branch says (languages, contributors, license), star them, and |
| 239 | publish [releases](/guides/releases/). Deleting, purging |
| 240 | and changing visibility need `confirm`, the repository's full name typed |
| 241 | out. |
| 242 | |
| 243 | | Action | What it does | Required | Scope | |
| 244 | | --- | --- | --- | --- | |
| 245 | | [`list`](/reference/api/repositories/list-repos/) | Repositories you can see, optionally filtered by `query`. | None | `repo:read` | |
| 246 | | [`get`](/reference/api/repositories/get-repo/) | One repository's details. | `repo` | `repo:read` | |
| 247 | | [`tarball`](/reference/api/repositories/download-tarball-archive/) | A link to a branch, tag or commit (`ref`, the default branch when left out) as a `.tar.gz` that needs no token, good for 10 minutes, as `url`, with the `commit` it is of. | `repo` | `code:read` | |
| 248 | | [`zipball`](/reference/api/repositories/download-zipball-archive/) | The same as a `.zip`. | `repo` | `code:read` | |
| 249 | | [`create`](/reference/api/repositories/create-repo/) | Create a repository in one of your workspaces, empty or as a copy of a public git repository (`import_url`). `workspace` may be left out if you belong to exactly one. | `name` | `repo:write` | |
| 250 | | [`update`](/reference/api/repositories/update-repo/) | Change its `description`, `website`, `topics` and `default_branch`, whether its default branch is `protected`, and whether it is `private`. Maintain role; `protected`, `private` and `default_branch` need Admin, and `private` the [member privileges](/guides/workspaces/#member-privileges) unless you are an owner. | `repo` | `repo:write` | |
| 251 | | [`get_settings`](/reference/api/repositories/get-repo-settings/) | How it handles pull requests: how they merge, and the default branch's required checks, approvals, bypassing checks, being up to date and merge queue as its [rulesets](/guides/rules/) stack. | `repo` | `repo:read` | |
| 252 | | [`update_settings`](/reference/api/repositories/update-repo-settings/) | Change those settings. Only the fields given change; `required_checks` replaces the whole list. Maintain role. | `repo` | `repo:write` | |
| 253 | | [`check_names`](/reference/api/repositories/list-check-names/) | The check names reported on its commits in the last 30 days, most recent first, each with `name`, `events` and `last_seen`: the names `required_checks` takes. | `repo` | `repo:read` | |
| 254 | | [`list_rulesets`](/reference/api/rules/list-repo-rulesets/) | Its [rulesets](/guides/rules/); `include_parents` adds the workspace's that hold in it. | `repo` | `repo:read` | |
| 255 | | [`get_ruleset`](/reference/api/rules/get-repo-ruleset/) | One ruleset by `id`. | `repo`, `id` | `repo:read` | |
| 256 | | [`create_ruleset`](/reference/api/rules/create-repo-ruleset/) | Create one: `ruleset_name`, `enforcement`, `target`, `conditions`, `bypass_actors`, `rules`. Admin role. | `repo` | `repo:admin` | |
| 257 | | [`update_ruleset`](/reference/api/rules/update-repo-ruleset/) | Change one; fields left out stay. Admin role. | `repo`, `id` | `repo:admin` | |
| 258 | | [`delete_ruleset`](/reference/api/rules/delete-repo-ruleset/) | Delete one. Admin role. | `repo`, `id` | `repo:admin` | |
| 259 | | [`branch_rules`](/reference/api/rules/get-branch-rules/) | Every rule that holds for a `branch` (or, with `target` `tag`, a tag), with the ruleset each comes from. | `repo`, `branch` | `repo:read` | |
| 260 | | [`rule_evaluations`](/reference/api/rules/list-rule-evaluations/) | How its rules judged pushes and merges, newest first, with 30 days of insights. Write role. | `repo` | `repo:read` | |
| 261 | | [`codeowners`](/reference/api/repositories/get-codeowners-errors/) | Its [CODEOWNERS file](/guides/codeowners/) checked as a linter would, on `ref` (the default branch unless you say): its `path`, `rules`, `sections`, and `errors`, each with `line`, `kind`, `token` and `message`. Read role. | `repo` | `repo:read` | |
| 262 | | [`list_labels`](/reference/api/labels-and-milestones/list-labels/) | Its labels by name, each with `color`, `description`, and how many `issues` and `pulls` carry it. | `repo` | `repo:read` | |
| 263 | | [`create_label`](/reference/api/labels-and-milestones/create-label/) | Create a label named `label`, with `color` (six hex digits; chosen from the name when left out) and `description`. Write role. | `repo`, `label` | `issues:write` | |
| 264 | | [`update_label`](/reference/api/labels-and-milestones/update-label/) | Change a label's `new_name`, `color` or `description`. Renaming renames it on everything that carries it. Write role. | `repo`, `label` | `issues:write` | |
| 265 | | [`delete_label`](/reference/api/labels-and-milestones/delete-label/) | Delete a label, from everything that carries it. Write role. | `repo`, `label` | `issues:write` | |
| 266 | | [`add_default_labels`](/reference/api/labels-and-milestones/add-default-labels/) | Add the default labels it is missing. Write role. | `repo` | `issues:write` | |
| 267 | | [`list_milestones`](/reference/api/labels-and-milestones/list-milestones/) | Its milestones, open ones soonest due first, each with `due_on`, `state`, `open_items` and `closed_items`. `state` filters them. | `repo` | `repo:read` | |
| 268 | | [`get_milestone`](/reference/api/labels-and-milestones/get-milestone/) | One milestone with its issues and pull requests. | `repo`, `milestone` | `repo:read` | |
| 269 | | [`create_milestone`](/reference/api/labels-and-milestones/create-milestone/) | Create a milestone with `title`, `description` and `due_on` (`YYYY-MM-DD`). Write role. | `repo`, `title` | `issues:write` | |
| 270 | | [`update_milestone`](/reference/api/labels-and-milestones/update-milestone/) | Change its `title`, `description`, `due_on` (`""` clears it) or `state` (`open` or `closed`). Write role. | `repo`, `milestone` | `issues:write` | |
| 271 | | [`delete_milestone`](/reference/api/labels-and-milestones/delete-milestone/) | Delete a milestone; what was in it is in none. Write role. | `repo`, `milestone` | `issues:write` | |
| 272 | | [`list_events`](/reference/api/repositories/list-events/) | Its timeline, newest first; `before` pages back. To follow it, give `after` (an event id): the events written after it come oldest first, and the last one's `id` is the next `after`. With `wait` (seconds, at most 25) a call that finds nothing holds on until a matching event is written. `types` and `numbers` (arrays) narrow it, with `since` and `limit` (at most 200). | `repo` | `repo:read` | |
| 273 | | [`languages`](/reference/api/repository-insights/get-languages/) | Its [languages](/guides/managing-repositories/#languages) by bytes, each with `color` and `percent`, for the default branch's `commit`; `pending` while it is first read. | `repo` | `repo:read` | |
| 274 | | [`contributors`](/reference/api/repository-insights/list-contributors/) | Its [contributors](/guides/managing-repositories/#contributors): `kind` (`user`, `g1t` or `author`), `commits` and `weeks`, and the repository's commits by week. | `repo` | `repo:read` | |
| 275 | | [`license`](/reference/api/repository-insights/get-license/) | The license its `LICENSE` file holds: `spdx_id`, `name`, `path`. | `repo` | `repo:read` | |
| 276 | | [`stargazers`](/reference/api/stars/list-stargazers/) | Who starred it, newest first, 100 a `page`. | `repo` | `repo:read` | |
| 277 | | [`starred`](/reference/api/stars/check-starred/) | Whether you starred it, and how many have. | `repo` | `account:read` | |
| 278 | | [`star`](/reference/api/stars/star-repo/) | Star it. People only. | `repo` | `account:write` | |
| 279 | | [`unstar`](/reference/api/stars/unstar-repo/) | Take your star back. | `repo` | `account:write` | |
| 280 | | [`list_starred`](/reference/api/stars/list-starred/) | Repositories you starred that you can still see. | None | `account:read` | |
| 281 | | [`list_releases`](/reference/api/releases/list-releases/) | Its [releases](/guides/releases/), newest first; drafts only for the Write role. | `repo` | `repo:read` | |
| 282 | | [`latest_release`](/reference/api/releases/get-latest-release/) | The newest published release that is neither a draft nor a prerelease. | `repo` | `repo:read` | |
| 283 | | [`get_release`](/reference/api/releases/get-release/) | One release by `id`. | `repo`, `id` | `repo:read` | |
| 284 | | [`get_release_by_tag`](/reference/api/releases/get-release-by-tag/) | The release of a `tag`. | `repo`, `tag` | `repo:read` | |
| 285 | | [`create_release`](/reference/api/releases/create-release/) | Publish a release of `tag_name` with `release_name` and `body`; a new tag is made at `target`. `draft`, `prerelease`. Write role. | `repo`, `tag_name` | `repo:write` | |
| 286 | | [`update_release`](/reference/api/releases/update-release/) | Change its `release_name`, `body`, `draft` or `prerelease`. Write role. | `repo`, `id` | `repo:write` | |
| 287 | | [`delete_release`](/reference/api/releases/delete-release/) | Delete a release; its tag stays. Write role. | `repo`, `id` | `repo:write` | |
| 288 | | [`rename_branch`](/reference/api/repositories/rename-branch/) | Rename a branch; its pull requests follow, and web addresses that name the old branch redirect. Write role; the default branch needs Admin. | `repo`, `branch`, `new_name` | `repo:write` | |
| 289 | | [`create_branch`](/reference/api/repositories/create-branch/) | Make a branch at another branch, a tag or a commit (`from`; the default branch when left out). Making one again at the commit `delete_branch` answered with restores it. Write role; the rules for creating it hold. | `repo`, `name` | `repo:write` | |
| 290 | | [`delete_branch`](/reference/api/repositories/delete-branch/) | Delete a branch, never the default; answers with the commit it pointed to. With `head`, a branch that has moved is left alone. Write role; the rules for deleting it hold. | `repo`, `branch` | `repo:write` | |
| 291 | | [`rename`](/reference/api/repositories/rename-repo/) | Give it a new name in its workspace; the old address redirects. Admin role. | `repo`, `name` | `repo:admin` | |
| 292 | | [`transfer`](/reference/api/repositories/transfer-repo/) | Move it to another workspace, keeping its name; the old address redirects. An owner, or an Admin when the member privileges allow it; and someone who can create a repository in the other workspace. See [transferring a repository](/guides/transferring-repositories/). | `repo`, `to` | `repo:admin` | |
| 293 | | [`archive`](/reference/api/repositories/archive-repo/) | Make it read-only: pushes and merges are refused, issues and pull requests are locked, and workflows stop. Admin role. | `repo` | `repo:admin` | |
| 294 | | [`unarchive`](/reference/api/repositories/unarchive-repo/) | Make it writable again. Admin role. | `repo` | `repo:admin` | |
| 295 | | [`set_visibility`](/reference/api/repositories/set-repo-visibility/) | Make it public or private; `confirm` is its full name. Admin role. | `repo`, `private`, `confirm` | `repo:admin` | |
| 296 | | [`delete`](/reference/api/repositories/delete-repo/) | Delete it; `confirm` is its full name. It can be restored for 30 days, then it is purged. Owners only. | `repo`, `confirm` | `repo:admin` | |
| 297 | | [`list_deleted`](/reference/api/repositories/list-deleted-repos/) | The workspace's recently deleted repositories, with when each is purged. Owners only; empty for anyone else. | `workspace` | `repo:read` | |
| 298 | | [`restore`](/reference/api/repositories/restore-repo/) | Bring a deleted repository back at the path it had. Owners only. | `repo` | `repo:admin` | |
| 299 | | [`purge`](/reference/api/repositories/purge-repo/) | Remove a deleted repository for good now, and free its name; `confirm` is its full name. Owners only. | `repo`, `confirm` | `repo:admin` | |
| 300 | | [`security_alerts`](/reference/api/security/list-security-alerts/) | Its security alerts: secrets found in pushes and history (`kind` `secret`) and dependencies with known vulnerabilities (`dependency`), each `open`, `dismissed` or `fixed`. `state` and `kind` filter them. Write role. | `repo` | `repo:read` | |
| 301 | | [`dismiss_alert`](/reference/api/security/dismiss-security-alert/) | Dismiss one by `id` with a `reason` and an optional `comment`. A secret takes `false_positive`, `used_in_tests`, `revoked` or `wont_fix`, and needs the Admin role, since a dismissed secret is let through push protection; a dependency takes `fix_started`, `no_bandwidth`, `tolerable_risk`, `inaccurate` or `not_used`, and needs Write. | `repo`, `id`, `reason` | `repo:admin` | |
| 302 | | [`reopen_alert`](/reference/api/security/reopen-security-alert/) | Open a dismissed alert again. The same roles as dismissing. | `repo`, `id` | `repo:admin` | |
| 303 | | [`why`](/reference/api/decisions-and-why/why/) | Why a line is the way it is: the `commit` that last changed `line` of `path` (at `ref`, or the default branch), the merged `pull` request it arrived in, its `issue`, the `decisions` recorded on the pull request, and the `sessions` entries behind the commit. | `repo`, `path`, `line` | `code:read` | |
| 304 | |
| 305 | `update_settings` takes `required_checks` (at most 20 names), |
| 306 | `required_approvals`, `allow_ignoring_checks`, `require_up_to_date`, |
| 307 | `auto_merge`, `merge_queue` and `require_code_owner_review`, which holds a |
| 308 | merge until the [code owners](/guides/codeowners/) of every file it changes |
| 309 | approve. See |
| 310 | [required status checks](/guides/pull-requests/#required-status-checks). |
| 311 | `update` with `private` or `default_branch` also needs `repo:admin`. |
| 312 | |
| 313 | See [managing a repository](/guides/managing-repositories/) for what each |
| 314 | of these changes, and what refuses it, and |
| 315 | [access and roles](/guides/access-and-roles/) for the role each needs. |
| 316 | |
| 317 | ## `issue` |
| 318 | |
| 319 | Issues: what should change. Before working on one, `work` gives everything |
| 320 | about it, and `claim` says you are on it; see |
| 321 | [sessions, claims and dependencies](/guides/sessions/). Issues and pull |
| 322 | requests share numbers, so `comment` works on either. |
| 323 | |
| 324 | | Action | What it does | Required | Scope | |
| 325 | | --- | --- | --- | --- | |
| 326 | | [`list`](/reference/api/issues/list-issues/) | Issues, newest first, by `state`, `label` and `milestone` (its number). | `repo` | `issues:read` | |
| 327 | | [`get`](/reference/api/issues/get-issue/) | An issue: description (which may say what done means, under **Definition of done**), labels, comments, and every pull request made for it. | `repo`, `number` | `issues:read` | |
| 328 | | [`create`](/reference/api/issues/create-issue/) | Open an issue, with `body`, `labels` and `milestone`. A label the repository lacks is created for someone with the Write role. `checks` is deprecated: its commands are added to the body under **Definition of done**, and the result carries a `deprecation` note. | `repo`, `title` | `issues:write` | |
| 329 | | [`update`](/reference/api/issues/update-issue/) | Change its title, body, labels, milestone, assignees or `blocked_by` (the issues that must land first). Labels, assignees and `blocked_by` each replace the whole set; `milestone` `null` or `0` takes it out of its milestone. A `blocked_by` that names the issue itself, something not an issue of the repository, or makes a cycle is refused. | `repo`, `number` | `issues:write` | |
| 330 | | [`labels`](/reference/api/issues/list-issue-labels/) | The labels an issue or pull request carries, with their colors. | `repo`, `number` | `issues:read` | |
| 331 | | [`add_labels`](/reference/api/issues/add-issue-labels/) | Add `labels` to an issue or pull request, keeping the ones it has. | `repo`, `number`, `labels` | `issues:write` | |
| 332 | | [`set_labels`](/reference/api/issues/set-issue-labels/) | Replace an issue's or pull request's labels with `labels`. | `repo`, `number`, `labels` | `issues:write` | |
| 333 | | [`remove_labels`](/reference/api/issues/remove-issue-labels/) | Take `label`, or several `labels`, off an issue or pull request; with neither, all of them. | `repo`, `number` | `issues:write` | |
| 334 | | [`close`](/reference/api/issues/close-issue/) | Close it as `completed` or `not_planned`. | `repo`, `number` | `issues:write` | |
| 335 | | [`reopen`](/reference/api/issues/reopen-issue/) | Reopen a closed issue. | `repo`, `number` | `issues:write` | |
| 336 | | [`comment`](/reference/api/issues/add-comment/) | Comment on an issue or a pull request; with `path` and `line`, on one line of a pull request's change. | `repo`, `number`, `body` | `issues:write` | |
| 337 | | [`edit_comment`](/reference/api/issues/edit-comment/) | Change a comment's text, by its id from `get`. Your own, or anyone's with the Maintain role or higher. Notes of what happened cannot be edited. | `repo`, `comment_id`, `body` | `issues:write` | |
| 338 | | [`delete_comment`](/reference/api/issues/delete-comment/) | Delete a comment, by its id. Your own, or anyone's with the Maintain role or higher. A review that approved or requested changes cannot be deleted. | `repo`, `comment_id` | `issues:write` | |
| 339 | | [`import`](/reference/api/integrations/import-issue/) | Open an issue from a Jira, Linear or Sentry item, linked to it. | `repo`, `reference` | `issues:write` | |
| 340 | | [`work`](/reference/api/claims-and-work/get-work/) | Everything to pick an issue up: its definition of done and required checks, active claims, sessions, pull requests (checks, mergeability, overlaps, queue place), what it is blocked by and blocks, decisions, and its recent coordination events. | `repo`, `number` | `issues:read` | |
| 341 | | [`claim`](/reference/api/claims-and-work/claim-issue/) | Say you are working on an open issue: advisory and expiring (`ttl_minutes`, 30 unless you say, at most 240), never a lock. Returns `others` already on it and what it is `blocked_by`. Claiming again, or a heartbeat of its `session_id`, renews it. | `repo`, `number` | `issues:write` | |
| 342 | | [`release`](/reference/api/claims-and-work/release-claim/) | Give up your claim, with an optional `reason`. | `repo`, `number` | `issues:write` | |
| 343 | | [`handoff`](/reference/api/claims-and-work/hand-off-issue/) | End your claim as handed off, `to` someone or anyone, with a `note` on where the work stands. | `repo`, `number`, `note` | `issues:write` | |
| 344 | | [`list_claims`](/reference/api/claims-and-work/list-claims/) | Claims on a repository's issues, newest first: active unless `state` says otherwise, `issue` for one. | `repo` | `issues:read` | |
| 345 | |
| 346 | ## `pull_request` |
| 347 | |
| 348 | Pull requests: start a change for an issue, record your session, mark it |
| 349 | ready, review and merge. Read `overlaps` and `behind` on `get` before going |
| 350 | far. |
| 351 | |
| 352 | | Action | What it does | Required | Scope | |
| 353 | | --- | --- | --- | --- | |
| 354 | | [`list`](/reference/api/pull-requests/list-pull-requests/) | Pull requests, newest first. `open` covers drafts and those ready for review. `label`, `milestone` and `base` filter them. | `repo` | `pull_requests:read` | |
| 355 | | [`get`](/reference/api/pull-requests/get-pull-request/) | Status, head commit, comments and reviews, who is asked to review (`pull.reviewers`, and `pull.team_reviewers` as `workspace/team`), its issue, its checks (`statuses`, and `required_checks`: each check the default branch requires, as `success`, `failure`, `pending` or `expected`), `code_owners` (whose approval the changed files need, and what is still `missing`), `behind`, and `overlaps`. | `repo`, `number` | `pull_requests:read` | |
| 356 | | [`changes`](/reference/api/pull-requests/get-pull-request-changes/) | The files it changes, with line-by-line diffs. | `repo`, `number` | `pull_requests:read` | |
| 357 | | [`create`](/reference/api/pull-requests/create-pull-request/) | Open a draft pull request with its own fork and get its git remote; or, with `branch`, one from a branch already pushed. Give `issue` whenever there is one. It merges into the default branch unless `base` names another. | `repo` | `pull_requests:write` | |
| 358 | | [`update`](/reference/api/pull-requests/update-pull-request/) | Change its `base` (the branch it merges into; Write role), `labels`, `milestone`, `assignees` or `reviewers`. `state` `open` reopens it and `closed` closes it. | `repo`, `number` | `pull_requests:write` | |
| 359 | | [`record_session`](/reference/api/sessions/record-session/) | Append entries to a pull request's session. Each has `kind` and `text`, and `tool` for tool entries. | `repo`, `number`, `entries` | `pull_requests:write` | |
| 360 | | [`read_session`](/reference/api/sessions/read-session/) | The recorded session, oldest first. `after` skips to entries after a sequence number. | `repo`, `number` | `pull_requests:read` | |
| 361 | | [`record_decision`](/reference/api/decisions-and-why/record-decision/) | Record a decision on a pull request, kept as `claimed`: a `kind` (`proposal`, `claim`, `fix` or `note`), a `summary`, and optional `evidence` (an object) and `session_id`. | `repo`, `number`, `kind`, `summary` | `pull_requests:write` | |
| 362 | | [`list_decisions`](/reference/api/decisions-and-why/list-decisions/) | The decision records on a pull request, or on an issue and its pull requests, oldest first, each with its `kind`, `confidence` (`claimed`, `tested` or `approved`), `summary` and `evidence`. | `repo`, `number` | `pull_requests:read` | |
| 363 | | [`ready`](/reference/api/pull-requests/mark-pull-request-ready/) | Mark a draft ready for review. The summary becomes its description. | `repo`, `number`, `summary` | `pull_requests:write` | |
| 364 | | [`draft`](/reference/api/pull-requests/convert-pull-request-to-draft/) | Turn a pull request that is ready for review back into a draft. It leaves the merge queue. Its author, or the Triage role. | `repo`, `number` | `pull_requests:write` | |
| 365 | | [`request_reviewers`](/reference/api/pull-requests/request-reviewers/) | Ask more people (`reviewers`, by username) or teams (`team_reviewers`, as `workspace/team` or a slug of the repository's workspace) to review it, added to whoever is asked already. Its author, or the Triage role. | `repo`, `number` | `pull_requests:write` | |
| 366 | | [`remove_requested_reviewers`](/reference/api/pull-requests/remove-requested-reviewers/) | Stop asking them. Reviews they gave stay. | `repo`, `number` | `pull_requests:write` | |
| 367 | | [`review`](/reference/api/pull-requests/review-pull-request/) | `approve`, or `request_changes` with a `body`. Not on your own pull request. | `repo`, `number`, `verdict` | `pull_requests:write` | |
| 368 | | [`close`](/reference/api/pull-requests/close-pull-request/) | Close it without merging. | `repo`, `number` | `pull_requests:write` | |
| 369 | | [`reopen`](/reference/api/pull-requests/reopen-pull-request/) | Reopen a closed pull request, as the draft it was if it was closed as one. Never a merged one. Its author, or the Triage role. | `repo`, `number` | `pull_requests:write` | |
| 370 | | [`merge`](/reference/api/pull-requests/merge-pull-request/) | Land it on its [base](/guides/base-branches/), or add it to the [merge queue](/guides/merge-queue/), once it meets every [rule](/guides/rules/) of its base, required checks included; `bypass_rules` merges past rules a ruleset lets you bypass. Into the default branch, it resolves its issue. `ignore_checks` bypasses required checks where the repository allows it. Write role. | `repo`, `number` | `pull_requests:write` | |
| 371 | | [`merge_queue`](/reference/api/pull-requests/get-merge-queue/) | The pull requests waiting to land, in order, each with the state it is tested in and how that went; then those that recently landed or left. | `repo` | `pull_requests:read` | |
| 372 | |
| 373 | `record_session` takes a list of `entries`, each with a `kind` (`prompt`, |
| 374 | `message`, `tool_call`, `tool_result` or `note`) and `text`, and `tool` for |
| 375 | tool entries. See [sessions and why-blame](/guides/why-blame/) and the |
| 376 | [merge queue](/guides/merge-queue/). g1t records `integration_failure`, |
| 377 | `integration_passed`, `approval` and `merge` decisions itself; see |
| 378 | [decision records](/guides/why-blame/#decision-records). |
| 379 | |
| 380 | ## `session` |
| 381 | |
| 382 | Your harness's session on a repository, so others see who is working on |
| 383 | what. Start one per run of your harness, heartbeat it, record what it does, |
| 384 | and end it. See [sessions](/guides/sessions/#sessions). |
| 385 | |
| 386 | | Action | What it does | Required | Scope | |
| 387 | | --- | --- | --- | --- | |
| 388 | | [`start`](/reference/api/sessions/start-session/) | Start a session: `harness` (`claude_code`, `codex`, `cursor`, `copilot` or `other`), and `harness_session_id`, which makes starting again return the same session. `issue`, `pull`, `branch`, `title` and `head_commit` as you know them. | `repo`, `harness` | `pull_requests:write` | |
| 389 | | [`update`](/reference/api/sessions/update-session/) | A heartbeat, and renews the session's claims; with fields, attaches an `issue` or `pull`, or sets `branch`, `head_commit` or `title`. | `repo`, `id` | `pull_requests:write` | |
| 390 | | [`record`](/reference/api/sessions/record-session-entries/) | Record up to 200 `entries`, each with `kind` and `text`, `tool` for tools, and a `key` that makes recording it again a no-op. | `repo`, `id`, `entries` | `pull_requests:write` | |
| 391 | | [`end`](/reference/api/sessions/end-session/) | End it, with an optional `reason`. | `repo`, `id` | `pull_requests:write` | |
| 392 | | [`get`](/reference/api/sessions/get-session/) | A session and its entries; `after` pages through them. | `repo`, `id` | `pull_requests:read` | |
| 393 | | [`list`](/reference/api/sessions/list-sessions/) | A repository's sessions, most recently heard from first, by `state` (`active`, `idle`, `ended`), `issue` or `pull`. | `repo` | `pull_requests:read` | |
| 394 | |
| 395 | ## `memory` |
| 396 | |
| 397 | What the project and its workspace remember for whoever works on it next, |
| 398 | person or agent: how to build, conventions, decisions and traps. Recall |
| 399 | before you start; remember one short fact at a time, never a secret. See |
| 400 | [memory](/guides/memory/). |
| 401 | |
| 402 | | Action | What it does | Required | Scope | |
| 403 | | --- | --- | --- | --- | |
| 404 | | [`recall`](/reference/api/memory/recall/) | What the project and its workspace remember, pinned first. `query` matches every word; `limit` caps each level. Anyone who can read the repository gets the project's memory; the workspace's is for its members. | `repo` | `memory:read` | |
| 405 | | [`remember`](/reference/api/memory/remember/) | Save one fact, convention, decision or gotcha for the next agent. `scope` is `project` (this codebase, the default) or `workspace` (true across its projects); `kind` is `fact`, `convention`, `decision` or `gotcha`. Text that looks like a secret is refused. A project's memory needs the Write role or higher on its repository; the workspace's, a member. | `repo`, `text` | `memory:write` | |
| 406 | |
| 407 | ## `workflow` |
| 408 | |
| 409 | Workflows in `.g1t/workflows/`: their runs, jobs and logs, and running, |
| 410 | cancelling or rerunning them; their artifacts; checks on commits (statuses, check runs and |
| 411 | check suites, a workflow job being a check run); a repository's deployments |
| 412 | and environments, with their protection rules; approving runs and |
| 413 | deployments; and the self-hosted runners workflows run on. See |
| 414 | [GitHub Actions](/guides/actions/), [Checks](/guides/checks/), |
| 415 | [Deployments API](/guides/deployments-api/) and |
| 416 | [self-hosted runners](/guides/self-hosted-runners/). |
| 417 | |
| 418 | | Action | What it does | Required | Scope | |
| 419 | | --- | --- | --- | --- | |
| 420 | | [`list`](/reference/api/actions/list-workflows/) | The workflows, with their events, state, problems, notes on what runs differently, manual-run inputs and last run. | `repo` | `workflows:read` | |
| 421 | | [`list_runs`](/reference/api/actions/list-runs-of-workflow/) | Runs, newest first; filter by `workflow`, `branch`, `event`, `pull` or `sha`. | `repo` | `workflows:read` | |
| 422 | | [`get_run`](/reference/api/actions/get-workflow-run/) | A run with its jobs, their steps and annotations, and its `attempts`; `attempt` reads an earlier attempt, with the jobs it had then. | `repo`, `id` | `workflows:read` | |
| 423 | | [`job_logs`](/reference/api/actions/get-job-logs/) | A job's log after `after`; `done` says if more will come. | `repo`, `job` | `workflows:read` | |
| 424 | | [`dispatch`](/reference/api/actions/dispatch-workflow/) | Run a `workflow_dispatch` workflow on `ref` with `inputs`. Write role. | `repo`, `workflow` | `workflows:write` | |
| 425 | | [`cancel`](/reference/api/actions/cancel-workflow-run/) | Cancel a run: running jobs stop their step and run their cleanup steps first. `force` (or cancelling again) stops them outright. Write role. | `repo`, `id` | `workflows:write` | |
| 426 | | [`rerun`](/reference/api/actions/rerun-workflow-run/) | Run it again as a new attempt; `failed_only` for the jobs that did not succeed, `job` for one job and those that need it, `debug` for debug logging. Write role. | `repo`, and `id` or `job` | `workflows:write` | |
| 427 | | [`update`](/reference/api/actions/update-workflow/) | Turn a workflow on or off. Maintain role. | `repo`, `workflow`, `enabled` | `workflows:write` | |
| 428 | | [`list_artifacts`](/reference/api/actions/list-artifacts/) | The repository's artifacts, newest first, with size, digest and expiry; `name`, `page`, `per_page`. | `repo` | `workflows:read` | |
| 429 | | [`run_artifacts`](/reference/api/actions/list-workflow-run-artifacts/) | One run's artifacts; `name`. | `repo`, `id` (the run) | `workflows:read` | |
| 430 | | [`get_artifact`](/reference/api/actions/get-artifact/) | One artifact by its number. | `repo`, `id` | `workflows:read` | |
| 431 | | [`download_artifact`](/reference/api/actions/download-artifact/) | A link to its zip that needs no token, good for 10 minutes, as `url`. | `repo`, `id` | `workflows:read` | |
| 432 | | [`delete_artifact`](/reference/api/actions/delete-artifact/) | Delete it before it expires. Write role. | `repo`, `id` | `workflows:write` | |
| 433 | | [`artifact_retention`](/reference/api/actions/get-artifact-retention/) | The days the repository keeps artifacts, and the most it may. | `repo` | `workflows:read` | |
| 434 | | [`set_artifact_retention`](/reference/api/actions/set-artifact-retention/) | Set those days, 1 to 90. Maintain role. | `repo`, `days` | `workflows:write` | |
| 435 | | [`combined_status`](/reference/api/checks/get-combined-status/) | A commit's statuses, one per context, and the `state` they add up to. `ref` is a SHA, branch or tag. | `repo`, `ref` | `checks:read` | |
| 436 | | [`list_statuses`](/reference/api/checks/list-commit-statuses/) | A commit's statuses, newest first. | `repo`, `ref` | `checks:read` | |
| 437 | | [`set_status`](/reference/api/checks/create-commit-status/) | Set a status: `state`, `context`, `description`, `target_url`. Write role. | `repo`, `sha`, `state` | `checks:write` | |
| 438 | | [`list_check_runs`](/reference/api/checks/list-check-runs-for-ref/) | A commit's check runs, workflow jobs included; `check_name`, `status`, `app`, `filter` (`latest` or `all`). | `repo`, `ref` | `checks:read` | |
| 439 | | [`get_check_run`](/reference/api/checks/get-check-run/) | One check run with its report: `cr_…`, or a job's `job_…`. | `repo`, `id` | `checks:read` | |
| 440 | | [`check_run_annotations`](/reference/api/checks/list-check-run-annotations/) | What a check run says about lines of files. | `repo`, `id` | `checks:read` | |
| 441 | | [`create_check_run`](/reference/api/checks/create-check-run/) | Report a check run: `status`, `conclusion`, `output` with `annotations`, `actions`, `app`. Write role. | `repo`, `name`, `head_sha` | `checks:write` | |
| 442 | | [`update_check_run`](/reference/api/checks/update-check-run/) | Move a check run on or complete it; annotations are added. Write role. | `repo`, `id` | `checks:write` | |
| 443 | | [`rerequest_check_run`](/reference/api/checks/rerequest-check-run/) | Ask its reporter to run it again; a job's run runs again (also `workflows:write`). Write role. | `repo`, `id` | `checks:write` | |
| 444 | | [`list_check_suites`](/reference/api/checks/list-check-suites-for-ref/) | A commit's check suites: one per reporter, and one per workflow run. | `repo`, `ref` | `checks:read` | |
| 445 | | [`get_check_suite`](/reference/api/checks/get-check-suite/) | One check suite: `cs_…`, or a workflow run's `run_…`. | `repo`, `id` | `checks:read` | |
| 446 | | [`rerequest_check_suite`](/reference/api/checks/rerequest-check-suite/) | Ask its reporter to run it again; a workflow run runs again (also `workflows:write`). Write role. | `repo`, `id` | `checks:write` | |
| 447 | | [`list_deployments`](/reference/api/deployments/list-deployments/) | Deployments wherever they run, newest first; filter by `environment`, `ref`, `sha`, `task`, `state`, `source` (`api`, `actions` or `g1t_page`) or `creator`, and page with `page` and `per_page`. | `repo` | `deployments:read` | |
| 448 | | [`get_deployment`](/reference/api/deployments/get-deployment/) | One deployment with every status it has had, oldest first. | `repo`, `id` | `deployments:read` | |
| 449 | | [`create_deployment`](/reference/api/deployments/create-deployment/) | Report a deployment of `ref` to an `environment` (`production` unless you say), with optional `sha`, `task`, `description`, `payload`, `production_environment`, `transient_environment`, first `state`, `environment_url` and `log_url`. Write role. | `repo`, `ref` | `deployments:write` | |
| 450 | | [`deployment_statuses`](/reference/api/deployments/list-deployment-statuses/) | A deployment's statuses, newest first. | `repo`, `id` | `deployments:read` | |
| 451 | | [`create_deployment_status`](/reference/api/deployments/create-deployment-status/) | Report where a deployment is: `state` (`queued`, `in_progress`, `success`, `failure`, `error` or `inactive`), with optional `description`, `environment_url`, `log_url` and `auto_inactive`. Not for a g1t.page build. Write role. | `repo`, `id`, `state` | `deployments:write` | |
| 452 | | [`list_environments`](/reference/api/deployments/list-environments/) | Environments with their address, current and latest deployments, production first. | `repo` | `deployments:read` | |
| 453 | | [`get_environment`](/reference/api/deployments/get-environment/) | One environment by name, with its protection rules. | `repo`, `environment` | `deployments:read` | |
| 454 | | [`start_deployment_build`](/reference/api/deployments/start-deployment-build/) | From a running workflow job, with the job's own token only: open a g1t.page build of a `project` (optional when the repository has one with Deployments on) that the job builds itself with `g1t-runner deploy`, optionally at `sha`. Production for a run on the production branch, a preview otherwise. Returns `deploy_id`, `token`, `kind`, `url`, `build_env` and `build_secrets`. See [deploying from a workflow](/guides/deployments/#deploying-from-a-workflow). | `repo` | `deployments:write` | |
| 455 | | [`update_environment`](/reference/api/run-protection/update-environment/) | Set an environment's [protection rules](/guides/actions/#environments): `reviewers` (up to 6, `{"type": "User" or "Team", "name"}`), `prevent_self_review`, `wait_timer` (minutes), `deployment_branch_policy`, `branch_policies` and `can_admins_bypass`. Admin role. | `repo`, `environment` | `repo:admin` | |
| 456 | | [`delete_environment`](/reference/api/run-protection/delete-environment/) | Remove an environment's protection rules; its secrets and deployments stay. Admin role. | `repo`, `environment` | `repo:admin` | |
| 457 | | [`pending_deployments`](/reference/api/run-protection/get-pending-deployments/) | The environments holding a run's jobs: their state, reviewers, wait timer, jobs, and whether you may approve. | `repo`, `id` | `workflows:read` | |
| 458 | | [`review_deployments`](/reference/api/run-protection/review-pending-deployments/) | Approve or reject a run's jobs for `environment_names` (every waiting one if left out), with a `comment`. One of the environment's reviewers, or an admin. | `repo`, `id`, `state` | `workflows:write` | |
| 459 | | [`approve_run`](/reference/api/run-protection/approve-workflow-run/) | Let a pull request's run from outside start ([approval](/guides/actions/#pull-requests-from-outside)). Write role. | `repo`, `id` | `workflows:write` | |
| 460 | | [`get_permissions`](/reference/api/run-protection/get-workflow-permissions/) | What a job's token gets when its workflow writes no `permissions:` (`read` or `write`), the workspace's maximum, and whether jobs may open and approve pull requests. | `repo` | `repo:read` | |
| 461 | | [`set_permissions`](/reference/api/run-protection/set-workflow-permissions/) | Set `default_workflow_permissions` (`read`, `write` or `inherit`) and `can_approve_pull_request_reviews`. Admin role. | `repo` | `repo:admin` | |
| 462 | | [`get_workspace_permissions`](/reference/api/run-protection/get-workspace-workflow-permissions/) | A workspace's default for new repositories, its maximum, and whether its repositories may let jobs open and approve pull requests. Members. | `workspace` | `workspace:read` | |
| 463 | | [`set_workspace_permissions`](/reference/api/run-protection/set-workspace-workflow-permissions/) | Change them: `default_workflow_permissions`, `max_workflow_permissions`, `can_approve_pull_request_reviews`. Owners. | `workspace` | `workspace:admin` | |
| 464 | | [`list_managed_workflows`](/reference/api/run-protection/list-workspace-managed-workflows/) | The [workflows a workspace manages](/guides/actions/#workflows-a-workspace-manages) in its repositories, each with its source, the commit it was copied at, its `mode`, `repositories` and `visibility`, and the copy that runs. Owners. | `workspace` | `workspace:read` | |
| 465 | | [`add_managed_workflow`](/reference/api/run-protection/create-workspace-managed-workflow/) | Run a workflow file of one of the workspace's repositories (`source`, `owner/repo/.g1t/workflows/file.yml@ref`, copied now) in its repositories as `managed/<name>.yml`: `mode` `required` or `default`, `repositories` (names and patterns, `!` excludes; empty for all) and `visibility` (`all`, `public` or `private`; a private source needs `private`). Owners. | `workspace`, `name`, `source`, `mode` | `workspace:admin` | |
| 466 | | [`update_managed_workflow`](/reference/api/run-protection/update-workspace-managed-workflow/) | Change one's `source`, `mode`, `repositories` or `visibility`; `refresh` copies its source again. Owners. | `workspace`, `workflow` | `workspace:admin` | |
| 467 | | [`remove_managed_workflow`](/reference/api/run-protection/delete-workspace-managed-workflow/) | Take one out of every repository; its runs stay. Owners. | `workspace`, `workflow` | `workspace:admin` | |
| 468 | | [`get_approval_policy`](/reference/api/run-protection/get-fork-pr-approval/) | Which pull requests' runs wait for approval. | `repo` | `repo:read` | |
| 469 | | [`set_approval_policy`](/reference/api/run-protection/set-fork-pr-approval/) | Set `approval_policy`: `first_time_contributors`, `outside_contributors` or `all_external_contributors`. Admin role. | `repo`, `approval_policy` | `repo:admin` | |
| 470 | | [`get_access`](/reference/api/run-protection/get-actions-access/) | Who may use this private repository's actions and reusable workflows: `access_level` `none` (only itself) or `organization` (the workspace's private repositories). | `repo` | `repo:read` | |
| 471 | | [`set_access`](/reference/api/run-protection/set-actions-access/) | Set `access_level`: `none` or `organization`. Admin role. | `repo`, `access_level` | `repo:admin` | |
| 472 | | [`repository_dispatch`](/reference/api/run-protection/create-repository-dispatch/) | Start the default branch's `repository_dispatch` workflows for `event_type`, with `client_payload`. Write role. | `repo`, `event_type` | `code:write` | |
| 473 | | [`list_runners`](/reference/api/runners/list-runners-for-workspace/) | [Self-hosted runners](/guides/self-hosted-runners/): a workspace's (`workspace`), or a repository's own and the workspace's it may use (`repo`), with status, labels and what each is running. | `workspace` or `repo` | `runners:read` | |
| 474 | | [`create_runner_token`](/reference/api/runners/create-runner-registration-token-for-workspace/) | A registration token for `g1t-runner register`, an hour long; `group` for a workspace's. Owners, or a repository's admins; not workspace tokens. | `workspace` or `repo` | `runners:admin` | |
| 475 | | [`remove_runner`](/reference/api/runners/remove-runner-for-workspace/) | Remove a runner; a job it is running fails. | `workspace` or `repo`, `id` | `runners:admin` | |
| 476 | | [`list_runner_groups`](/reference/api/runners/list-runner-groups/) | A workspace's runner groups and the repositories each serves. | `workspace` | `runners:read` | |
| 477 | | [`create_runner_group`](/reference/api/runners/create-runner-group/) | A group for some `repositories` (empty for all). Owners. | `workspace`, `name` | `runners:admin` | |
| 478 | | [`update_runner_group`](/reference/api/runners/update-runner-group/) | Rename a group or change its repositories. Owners. | `workspace`, `id` | `runners:admin` | |
| 479 | | [`delete_runner_group`](/reference/api/runners/delete-runner-group/) | Delete a group; its runners join the default. Owners. | `workspace`, `id` | `runners:admin` | |
| 480 | | [`get_runner_settings`](/reference/api/runners/get-runner-settings-for-workspace/) | Whether g1t's own runs for a repository (checks, merge checks and merge-queue test runs) run on self-hosted runners and on which labels, and whether pull requests from forks may use them. | `workspace` or `repo` | `runners:read` | |
| 481 | | [`update_runner_settings`](/reference/api/runners/update-runner-settings-for-workspace/) | Change them: `agents_on_self_hosted`, `agent_labels`, `fork_pull_requests`, or `inherit` for a repository. | `workspace` or `repo` | `runners:admin` | |
| 482 | |
| 483 | ## `observability` |
| 484 | |
| 485 | What a project's running software did in production, to debug it: its |
| 486 | requests, logs, traces, grouped errors and metrics, from its apps on |
| 487 | g1t.page and from OpenTelemetry sent from anywhere. Name the project with |
| 488 | `workspace` and `project` (its slug). `from` and `to` are RFC 3339 times or |
| 489 | Unix milliseconds, the last 24 hours unless you say; `environment` and |
| 490 | `service` narrow any list. Reading needs a role of your own on the |
| 491 | project's repository, even when it is public. A project's settings, ingest |
| 492 | tokens, exports and usage are in the [REST API](/reference/api/observability/get-observability-settings/) |
| 493 | only. See [Observability](/guides/observability/). |
| 494 | |
| 495 | | Action | What it does | Required | Scope | |
| 496 | | --- | --- | --- | --- | |
| 497 | | [`overview`](/reference/api/observability/get-observability-overview/) | Requests, errors, error rate, latency and CPU percentiles over a period, against the period before; by route, deployment (newest first, so a regression points at the deployment it began with), service and region; `deployment_id`, `step`. | `workspace`, `project` | `observability:read` | |
| 498 | | [`requests`](/reference/api/observability/list-requests/) | Requests answered, newest first; filter by words in `q`, `status` (`5xx`, `404`, comma-separated), `errors_only`, `route`, `min_duration_ms` and `deployment_id`; page with `cursor` and `limit`. | `workspace`, `project` | `observability:read` | |
| 499 | | [`request`](/reference/api/observability/get-request/) | One request with every log line it wrote. | `workspace`, `project`, `id` | `observability:read` | |
| 500 | | [`logs`](/reference/api/observability/list-logs/) | Search a project's logs: words or a phrase in `q`, `level` (`error,warn`), `trace_id`, `request_id`, `deployment_id`; page with `cursor` and `limit`. | `workspace`, `project` | `observability:read` | |
| 501 | | [`traces`](/reference/api/observability/list-traces/) | Traces, newest first, each its root span, duration, span and error counts; `q`, `errors_only`, `min_duration_ms`. | `workspace`, `project` | `observability:read` | |
| 502 | | [`trace`](/reference/api/observability/get-trace/) | One trace: every span with its timing, status, attributes and events, and the logs written under it. | `workspace`, `project`, `trace_id` | `observability:read` | |
| 503 | | [`errors`](/reference/api/observability/list-errors/) | Errors grouped by exception, most recently seen first, each with its count, the deployment that brought it in, its last request and trace, and its `state`; filter by `state`. | `workspace`, `project` | `observability:read` | |
| 504 | | [`update_error`](/reference/api/observability/update-error/) | Resolve, ignore or reopen an error group (`state`), or link the issue made for it (`issue_number`, null to unlink). Triage role. | `workspace`, `project`, `fingerprint` | `observability:write` | |
| 505 | | [`metrics`](/reference/api/observability/list-metrics/) | The metrics the project's software sends, with their kind, unit and services. | `workspace`, `project` | `observability:read` | |
| 506 | | [`metric`](/reference/api/observability/get-metric/) | One metric over time: `aggregate` (`avg`, `sum`, `min`, `max`, `p50`, `p95`, `p99`), `group_by` an attribute, `step`. | `workspace`, `project`, `metric` | `observability:read` | |
| 507 | |
| 508 | ## `package` |
| 509 | |
| 510 | A workspace's [packages](/guides/packages/) in every registry: their |
| 511 | versions and downloads, deleting and restoring them within 30 days, their |
| 512 | visibility and repository, the people and teams with a role on them, and |
| 513 | which repositories' workflows may use them. Every action takes |
| 514 | `workspace`; all but `list` also take `package_type` (`container`, `npm`, |
| 515 | `cargo`, `maven`, `nuget`, `rubygems` or `composer`) and `package_name`. |
| 516 | Reading access and every change also need the Admin role on the package. |
| 517 | |
| 518 | | Action | What it does | Required | Scope | |
| 519 | | --- | --- | --- | --- | |
| 520 | | [`list`](/reference/api/packages/list-packages/) | The workspace's packages you may pull, by `package_type` and `q`; with `state` `deleted`, its deleted ones you administer. | `workspace` | `packages:read` | |
| 521 | | [`get`](/reference/api/packages/get-package/) | One package: address, visibility, repository, versions, downloads. | `package_type`, `package_name` | `packages:read` | |
| 522 | | [`versions`](/reference/api/packages/list-package-versions/) | Its versions with tags and downloads, newest first; `state` `deleted` for deleted ones. | `package_type`, `package_name` | `packages:read` | |
| 523 | | [`get_version`](/reference/api/packages/get-package-version/) | One version by id, version, digest or tag. | `version_id` | `packages:read` | |
| 524 | | [`update`](/reference/api/packages/update-package/) | Set `visibility` (unlinked packages), or `inherit_access` (linked ones). | `package_type`, `package_name` | `packages:write` | |
| 525 | | [`link`](/reference/api/packages/link-package/) | Link it to a `repository` of its workspace; Admin on the repository too. | `repository` | `packages:write` | |
| 526 | | [`unlink`](/reference/api/packages/unlink-package/) | Unlink it: the workspace's, private. | `package_type`, `package_name` | `packages:write` | |
| 527 | | [`access`](/reference/api/packages/list-package-access/) | People and teams with a role on it, and `inherit_access`. | `package_type`, `package_name` | `packages:read` | |
| 528 | | [`set_access`](/reference/api/packages/set-package-access/) | Give `username` or `team` a `role`: `read`, `write` or `admin`. | `role` | `packages:write` | |
| 529 | | [`remove_access`](/reference/api/packages/remove-package-access/) | Take `username`'s or `team`'s role away. | `package_type`, `package_name` | `packages:write` | |
| 530 | | [`actions_access`](/reference/api/packages/list-package-actions-access/) | Repositories whose workflows may use it; the linked one is always listed. | `package_type`, `package_name` | `packages:read` | |
| 531 | | [`set_actions_access`](/reference/api/packages/set-package-actions-access/) | Let a `repository`'s workflows use it with `role` `read` or `write`. | `repository`, `role` | `packages:write` | |
| 532 | | [`remove_actions_access`](/reference/api/packages/remove-package-actions-access/) | Stop a `repository`'s workflows using it. | `repository` | `packages:write` | |
| 533 | | [`delete`](/reference/api/packages/delete-package/) | Delete it, restorable for 30 days; its name stays taken until then. | `package_type`, `package_name` | `packages:delete` | |
| 534 | | [`restore`](/reference/api/packages/restore-package/) | Restore a deleted package. | `package_type`, `package_name` | `packages:delete` | |
| 535 | | [`delete_version`](/reference/api/packages/delete-package-version/) | Delete a version, restorable for 30 days. | `version_id` | `packages:delete` | |
| 536 | | [`restore_version`](/reference/api/packages/restore-package-version/) | Restore a deleted version. | `version_id` | `packages:delete` | |
| 537 | |
| 538 | ## `secret` |
| 539 | |
| 540 | A repository's or a workspace's secrets and variables, which workflows and |
| 541 | deployments read. Give `repo` for a repository's, or `workspace` for a |
| 542 | workspace's own. Secret values are never returned. |
| 543 | |
| 544 | | Action | What it does | Required | Scope | |
| 545 | | --- | --- | --- | --- | |
| 546 | | [`list_secrets`](/reference/api/secrets-and-variables/list-actions-secrets/) | Secrets' rows: key, environments, who reads them. Never values. | None | `secrets:read` | |
| 547 | | [`set_secret`](/reference/api/secrets-and-variables/set-actions-secret/) | Add or change a secret's row: `value`, and optionally `id`, `environments`, `available_to`, `projects`, `note`, and `brokered_hosts` to broker it (jobs get a stand-in; g1t fills in the value on requests to those hosts). | `setting` | `secrets:admin` | |
| 548 | | [`delete_secret`](/reference/api/secrets-and-variables/delete-actions-secret/) | Remove one row (`id`) or every row of the key. | `setting` | `secrets:admin` | |
| 549 | | [`list_variables`](/reference/api/secrets-and-variables/list-actions-variables/) | Config rows with their values. | None | `secrets:read` | |
| 550 | | [`set_variable`](/reference/api/secrets-and-variables/set-actions-variable/) | Add or change a config row, as for secrets. | `setting` | `secrets:admin` | |
| 551 | | [`delete_variable`](/reference/api/secrets-and-variables/delete-actions-variable/) | Remove one row (`id`) or every row of the key. | `setting` | `secrets:admin` | |
| 552 | |
| 553 | ## `security` |
| 554 | |
| 555 | A repository's [security](/guides/security/): secret scanning alerts and |
| 556 | push protection bypasses, [custom patterns](/guides/security/secret-protection/#custom-patterns), |
| 557 | [code scanning](/guides/security/code-scanning/) and SARIF uploads, |
| 558 | vulnerability alerts, the [dependency graph and its SBOM](/guides/security/supply-chain/), |
| 559 | dependency review, settings, and a workspace's |
| 560 | [overview](/guides/security/security-overview/). `secret_alerts` is the |
| 561 | default action. Findings are shown only to those with Write on the |
| 562 | repository, and to the workspace's security managers; on private repositories, some actions need the |
| 563 | g1t plan, as [Security and quality](/guides/security/pricing/), and are |
| 564 | refused with `402` without it. |
| 565 | |
| 566 | | Action | What it does | Required | Scope | |
| 567 | | --- | --- | --- | --- | |
| 568 | | [`secret_alerts`](/reference/api/secret-scanning/list-secret-scanning-alerts/) | Secret scanning alerts, newest first: `repo`, or `workspace` for all of one. Filter with `state`, `secret_type`, `validity` and `bypassed`. Never the secret itself. | None | `security:read` | |
| 569 | | [`secret_alert`](/reference/api/secret-scanning/get-secret-scanning-alert/) | One alert by `id`, with where it was found, its activity and bypass requests, and whether you may bypass it. | `repo`, `id` | `security:read` | |
| 570 | | [`update_secret_alert`](/reference/api/secret-scanning/update-secret-scanning-alert/) | Dismiss (`state` `dismissed`, `reason` `false_positive`, `used_in_tests`, `revoked` or `wont_fix`, optional `comment`) or reopen (`state` `open`). Write role, or a security manager. | `repo`, `id`, `state` | `security:write` | |
| 571 | | [`secret_locations`](/reference/api/secret-scanning/list-secret-scanning-locations/) | Every file, line and commit a secret is in. | `repo`, `id` | `security:read` | |
| 572 | | [`bypass`](/reference/api/secret-scanning/bypass-push-protection/) | Push past push protection for a blocked secret with a `reason` (`false_positive`, `used_in_tests`, `will_fix_later`), or ask to when the workspace delegates bypasses. | `repo`, `id`, `reason` | `security:write` | |
| 573 | | [`check_validity`](/reference/api/secret-scanning/check-secret-validity/) | Ask a landed secret's issuer whether it still works. | `repo`, `id` | `security:write` | |
| 574 | | [`bypass_requests`](/reference/api/secret-scanning/list-bypass-requests/) | A workspace's bypass requests, pending first; filter with `state` and `repo`. | `workspace` | `security:read` | |
| 575 | | [`review_bypass`](/reference/api/secret-scanning/review-bypass-request/) | `decision` `approve` or `deny` (owners and the repository's admins), or `cancel` your own. | `workspace`, `id`, `decision` | `security:write` | |
| 576 | | [`patterns`](/reference/api/secret-scanning/list-custom-patterns/) | Custom patterns: a repository's and its workspace's (`repo`), or a workspace's (`workspace`). | None | `security:read` | |
| 577 | | [`create_pattern`](/reference/api/secret-scanning/create-custom-pattern/) | Create a pattern: `pattern_name`, `pattern`, optional `before`, `after`, `test_strings`, and `publish`. | `pattern_name`, `pattern` | `security:write` | |
| 578 | | [`update_pattern`](/reference/api/secret-scanning/update-custom-pattern/) | Change, publish or unpublish one. | `id`, `pattern_name`, `pattern` | `security:write` | |
| 579 | | [`delete_pattern`](/reference/api/secret-scanning/delete-custom-pattern/) | Delete one; its alerts stay. | `id` | `security:write` | |
| 580 | | [`dry_run_pattern`](/reference/api/secret-scanning/dry-run-custom-pattern/) | Run a `pattern` over the default branch without saving it. | `pattern` | `security:write` | |
| 581 | | [`code_alerts`](/reference/api/code-scanning/list-code-scanning-alerts/) | Code scanning alerts, open and worst first: `repo`, or `workspace`. Filter with `state`, `severity`, `tool`, `rule_id`. | None | `security:read` | |
| 582 | | [`code_alert`](/reference/api/code-scanning/get-code-scanning-alert/) | One alert by `number`, with its activity and analyses. | `repo`, `number` | `security:read` | |
| 583 | | [`update_code_alert`](/reference/api/code-scanning/update-code-scanning-alert/) | Dismiss (`state` `dismissed`, `dismissed_reason` `false_positive`, `wont_fix` or `used_in_tests`) or reopen. | `repo`, `number`, `state` | `security:write` | |
| 584 | | [`analyses`](/reference/api/code-scanning/list-code-scanning-analyses/) | Analyses, newest first. | `repo` | `security:read` | |
| 585 | | [`upload_sarif`](/reference/api/code-scanning/upload-sarif/) | Upload a SARIF 2.1.0 file, gzipped and base64-encoded, for a `commit_sha` and `ref`. | `repo`, `commit_sha`, `ref`, `sarif` | `security:write` | |
| 586 | | [`sarif_upload`](/reference/api/code-scanning/get-sarif-upload/) | Whether an upload was read, its analyses and errors. | `repo`, `id` | `security:read` | |
| 587 | | [`vulnerability_alerts`](/reference/api/supply-chain/list-vulnerability-alerts/) | Vulnerability alerts: `repo`, or `workspace`. Filter with `state`, `severity`, `ecosystem`, `package`. | None | `security:read` | |
| 588 | | [`vulnerability_alert`](/reference/api/supply-chain/get-vulnerability-alert/) | One alert by `id`. | `repo`, `id` | `security:read` | |
| 589 | | [`update_vulnerability_alert`](/reference/api/supply-chain/update-vulnerability-alert/) | Dismiss (`state` `dismissed`, `reason` `fix_started`, `no_bandwidth`, `tolerable_risk`, `inaccurate` or `not_used`) or reopen. | `repo`, `id`, `state` | `security:write` | |
| 590 | | [`dependency_graph`](/reference/api/supply-chain/get-dependency-graph/) | Every package the lockfiles resolve, direct or transitive, with licenses. | `repo` | `security:read` | |
| 591 | | [`sbom`](/reference/api/supply-chain/get-sbom/) | The dependency graph as an SPDX 2.3 document, in `sbom`. | `repo` | `security:read` | |
| 592 | | [`compare_dependencies`](/reference/api/supply-chain/compare-dependencies/) | What changes between `basehead` (`base...head`), and whether it passes dependency review. | `repo`, `basehead` | `security:read` | |
| 593 | | [`settings`](/reference/api/security-settings/get-security-settings/) | A repository's security settings, and whether the paid features are on. | `repo` | `security:read` | |
| 594 | | [`update_settings`](/reference/api/security-settings/update-security-settings/) | Change `code_scanning_gate`, `dependency_review`, `review_fail_on`, `review_deny_licenses`, `review_comment`. Admin role, or a security manager. | `repo` | `security:write` | |
| 595 | | [`workspace_settings`](/reference/api/security-settings/get-workspace-security-settings/) | A workspace's delegated bypass and validity checks. | `workspace` | `security:read` | |
| 596 | | [`update_workspace_settings`](/reference/api/security-settings/update-workspace-security-settings/) | Turn `delegated_bypass` or `validity_checks` on or off. Owners and security managers. | `workspace` | `security:write` | |
| 597 | | [`overview`](/reference/api/security-settings/get-security-overview/) | A workspace's alerts by type and severity, trends and coverage. | `workspace` | `security:read` | |
| 598 | |
| 599 | ## `webhook` |
| 600 | |
| 601 | HTTPS addresses that are sent signed events as they happen. Give `repo` for |
| 602 | a repository's webhooks, or `workspace` for a workspace's own. See |
| 603 | [webhooks](/guides/webhooks/). |
| 604 | |
| 605 | | Action | What it does | Required | Scope | |
| 606 | | --- | --- | --- | --- | |
| 607 | | [`list`](/reference/api/webhooks/list-webhooks/) | The webhooks, with how each one's latest delivery went. A repository's need the Admin role; a workspace's, a member. | None | `webhooks:read` | |
| 608 | | [`create`](/reference/api/webhooks/create-webhook/) | Send events to an HTTPS address: `events` to choose them, `secret` to sign with. A ping is sent at once. | `url` | `webhooks:admin` | |
| 609 | | [`update`](/reference/api/webhooks/update-webhook/) | Change its `url`, `events`, or whether it is `active`. | `id` | `webhooks:admin` | |
| 610 | | [`delete`](/reference/api/webhooks/delete-webhook/) | Remove it and its delivery log. | `id` | `webhooks:admin` | |
| 611 | | [`ping`](/reference/api/webhooks/ping-webhook/) | Send it a ping. | `id` | `webhooks:admin` | |
| 612 | | [`list_deliveries`](/reference/api/webhooks/list-webhook-deliveries/) | Its latest deliveries, with request, response and retries. | `id` | `webhooks:read` | |
| 613 | | [`redeliver`](/reference/api/webhooks/redeliver-webhook/) | Send a delivery again. | `delivery` | `webhooks:admin` | |
| 614 | |
| 615 | ## `access` |
| 616 | |
| 617 | Who can do what in a repository: its people and their |
| 618 | [roles](/guides/access-and-roles/) (read, triage, write, maintain and |
| 619 | admin), invitations, outside collaborators, a workspace's base |
| 620 | permission, and a repository's [deploy keys](/guides/git/#deploy-keys). |
| 621 | |
| 622 | | Action | What it does | Required | Scope | |
| 623 | | --- | --- | --- | --- | |
| 624 | | [`list_collaborators`](/reference/api/access/list-collaborators/) | Everyone with a role on it, with the role, where it comes from (`owner`, `base` or `direct`) and whether they are members; the base permission; and, with the Admin role, pending invitations. Needs the Write role. | `repo` | `access:read` | |
| 625 | | [`get_permission`](/reference/api/access/get-collaborator-permission/) | Someone's role, where it comes from, and what it lets them do. Needs the Write role, or to be about yourself. | `repo`, `username` | `access:read` | |
| 626 | | [`add_collaborator`](/reference/api/access/add-collaborator/) | Give someone a role by username or email address. A member gets it at once; anyone else is invited, and becomes an outside collaborator on accepting. Needs the Admin role. On a free workspace, only members: inviting anyone else is refused with `402` until it starts the plan. | `repo`, `invitee`, `role` | `access:admin` | |
| 627 | | [`update_collaborator`](/reference/api/access/update-collaborator/) | Change someone's direct role, or their pending invitation's. Needs the Admin role. | `repo`, `username`, `role` | `access:admin` | |
| 628 | | [`remove_collaborator`](/reference/api/access/remove-collaborator/) | Take away someone's direct role. Needs the Admin role, or to be your own. | `repo`, `username` | `access:admin` | |
| 629 | | [`list_invitations`](/reference/api/access/list-repo-invitations/) | Its pending invitations. Needs the Admin role. | `repo` | `access:read` | |
| 630 | | [`revoke_invitation`](/reference/api/access/revoke-repo-invitation/) | Withdraw a pending invitation. Needs the Admin role. | `repo`, `id` | `access:admin` | |
| 631 | | [`set_base_permission`](/reference/api/access/set-base-permission/) | What every member gets on each repository: `none`, `read`, `write` (the default) or `admin`. Owners only. | `workspace`, `base_permission` | `access:admin` | |
| 632 | | [`list_outside_collaborators`](/reference/api/access/list-outside-collaborators/) | People with roles on its repositories who are not members, and what they can reach. Owners only. | `workspace` | `access:read` | |
| 633 | | [`list_deploy_keys`](/reference/api/access/list-deploy-keys/) | Its deploy keys: SSH keys that reach this one repository, each with its `fingerprint`, `read_only`, who added it and `last_used_at`. Needs the Admin role. | `repo` | `access:read` | |
| 634 | | [`get_deploy_key`](/reference/api/access/get-deploy-key/) | One deploy key. Needs the Admin role. | `repo`, `id` | `access:read` | |
| 635 | | [`add_deploy_key`](/reference/api/access/create-deploy-key/) | Add a deploy key: `key` (an OpenSSH public key), `title`, and `read_only`, true unless you send false. A key registered anywhere already is refused. Needs the Admin role. | `repo`, `key` | `access:admin` | |
| 636 | | [`remove_deploy_key`](/reference/api/access/delete-deploy-key/) | Delete a deploy key; anything using it stops at once. Needs the Admin role. | `repo`, `id` | `access:admin` | |
| 637 | |
| 638 | ## `team` |
| 639 | |
| 640 | [Teams](/guides/teams/): groups of a workspace's members, given roles on |
| 641 | repositories together, mentioned as `@workspace/team` and asked to review |
| 642 | together. Name a team by `workspace` and its slug, `team`. Any member may |
| 643 | create one; the workspace's owners and the team's maintainers manage it. A |
| 644 | `secret` team is seen only by its own people and the owners. Changes are |
| 645 | for people: a workspace's token cannot make them. |
| 646 | |
| 647 | | Action | What it does | Required | Scope | |
| 648 | | --- | --- | --- | --- | |
| 649 | | [`list`](/reference/api/teams/list-teams/) | The workspace's teams you can see, yours first; `query` narrows by name or slug. Members only. | `workspace` | `workspace:read` | |
| 650 | | [`get`](/reference/api/teams/get-team/) | One team: its `visibility`, `parent`, `notify`, `review_assignment`, counts, your `viewer_role` and whether you may change it (`can_manage`). | `workspace`, `team` | `workspace:read` | |
| 651 | | [`create`](/reference/api/teams/create-team/) | Create a team; you become its maintainer. Members may, unless the workspace's `team_creation` is `owners`. `slug` is made from `name` unless given; `visibility`, `parent`, `notify`, and `members` to add by username. | `workspace`, `name` | `workspace:admin` | |
| 652 | | [`update`](/reference/api/teams/update-team/) | Change its `name`, `slug`, `description`, `visibility`, `parent` (`""` for none), `notify` or `review_assignment`. Owners and its maintainers. | `workspace`, `team` | `workspace:admin` | |
| 653 | | [`delete`](/reference/api/teams/delete-team/) | Delete it; its child teams move up to its parent, and the roles it gave go. Owners and its maintainers. | `workspace`, `team` | `workspace:admin` | |
| 654 | | [`list_members`](/reference/api/teams/list-team-members/) | Its people and their `role` (`member` or `maintainer`); with `include_child_teams`, its child teams' people too, each with `via`. | `workspace`, `team` | `workspace:read` | |
| 655 | | [`set_member`](/reference/api/teams/set-team-member/) | Add a member of the workspace, or change their `role`. Owners and its maintainers. | `workspace`, `team`, `username` | `workspace:admin` | |
| 656 | | [`remove_member`](/reference/api/teams/remove-team-member/) | Take someone out. Owners and its maintainers; anyone may leave. | `workspace`, `team`, `username` | `workspace:admin` | |
| 657 | | [`list_child_teams`](/reference/api/teams/list-child-teams/) | The teams nested directly under it. | `workspace`, `team` | `workspace:read` | |
| 658 | | [`list_repos`](/reference/api/teams/list-team-repos/) | The repositories it has a role on, with `inherited_from` for one a parent gives it. | `workspace`, `team` | `workspace:read` | |
| 659 | | [`set_repo`](/reference/api/teams/set-team-repo/) | Give it a `role` (read, triage, write, maintain or admin) on a repository of its workspace, named by `repo` (its name, or `owner/name`). Admin role on the repository. | `workspace`, `team`, `repo`, `role` | `access:admin` | |
| 660 | | [`remove_repo`](/reference/api/teams/remove-team-repo/) | Take its role on a repository away. Admin role on the repository, an owner, or one of its maintainers. | `workspace`, `team`, `repo` | `access:admin` | |
| 661 | | [`set_review_assignment`](/reference/api/teams/set-team-review-assignment/) | Whom it picks when asked to review: `enabled`, `algorithm` (`round_robin` or `load_balance`), `count` (1 to 10), `skip_busy` and `busy_at`, `include_child_teams`, `excluded` and `notify_team`. Fields left out keep their value. Owners and its maintainers. | `workspace`, `team` | `workspace:admin` | |
| 662 | | [`list_user_teams`](/reference/api/teams/list-user-teams/) | The teams someone is in. Members only. | `workspace`, `username` | `workspace:read` | |
| 663 | |
| 664 | ## `workspace` |
| 665 | |
| 666 | Workspaces own repositories: create, update or delete one, invite members, |
| 667 | manage its members and owners, |
| 668 | connect [integrations](/guides/integrations/), read and |
| 669 | change its [projects](/guides/projects/) (what each is, where it runs, its |
| 670 | links), and keep your own |
| 671 | [pinned projects](/guides/workspaces/#pinned-and-recent-projects) at the top |
| 672 | of its sidebar. See [workspaces](/guides/workspaces/). |
| 673 | |
| 674 | | Action | What it does | Required | Scope | |
| 675 | | --- | --- | --- | --- | |
| 676 | | [`get`](/reference/api/workspaces/get-workspace/) | One workspace you belong to: its name, description and member count, its `base_permission` and `team_creation`, its [member privileges](/guides/workspaces/#member-privileges) (`members_can_…`) and `two_factor_requirement_enabled`. Members only. | `workspace` | `workspace:read` | |
| 677 | | [`create`](/reference/api/workspaces/create-workspace/) | Create a workspace. A new one is free, and each person owns at most one free workspace: refused with `402` while you own one, until it is on the plan or deleted. See [one free workspace per person](/guides/usage-and-billing/#one-free-workspace-per-person). | `slug` | `workspace:admin` | |
| 678 | | [`update`](/reference/api/workspaces/update-workspace/) | Change its display name and description, who may create its teams (`team_creation`: `members` or `owners`), its member privileges, whether it requires two-factor authentication (`two_factor_requirement_enabled`), and with the `access:admin` scope too, its `base_permission`. Only the fields given change; the slug never does. Owners only. | `workspace` | `workspace:admin` | |
| 679 | | [`list_members`](/reference/api/members/list-members/) | Its members, owners first, each with `role`, `org_roles` and, for owners asking, `two_factor`. Members only. | `workspace` | `workspace:read` | |
| 680 | | [`update_member`](/reference/api/members/update-member/) | Make someone an owner or a member (`role`), and give or take away `org_roles` (`billing_manager`, `security_manager`). Never leaves the workspace without an owner. Owners only. | `workspace`, `username` | `workspace:admin` | |
| 681 | | [`remove_member`](/reference/api/members/remove-member/) | Remove someone; their roles on its repositories and their teams go too. Owners only. | `workspace`, `username` | `workspace:admin` | |
| 682 | | [`transfer_ownership`](/reference/api/members/transfer-ownership/) | Hand it to another member: they become an owner, you a member. Owners only. | `workspace`, `username` | `workspace:admin` | |
| 683 | | [`leave`](/reference/api/members/leave-workspace/) | Leave it yourself. Never the last owner. | `workspace` | `account:write` | |
| 684 | | [`delete`](/reference/api/workspaces/delete-workspace/) | Delete an empty workspace whose billing is settled; `confirm` is its slug. Owners only. See [deleting a workspace](/guides/workspaces/#delete-a-workspace). | `workspace`, `confirm` | `workspace:admin` | |
| 685 | | [`list_invites`](/reference/api/invites/list-workspace-invites/) | A workspace's invites. Owners only. | `workspace` | `workspace:read` | |
| 686 | | [`invite_member`](/reference/api/invites/invite-member/) | Invite someone into a workspace by `username` or `email`, to join with `role` (`member` or `owner`; `member` when left out). Nobody joins without saying yes: they get an invitation to accept or decline. Owners only. A free workspace cannot invite: refused with `402` until it starts the plan. | `workspace`, and `username` or `email` | `workspace:admin` | |
| 687 | | [`revoke_invite`](/reference/api/invites/revoke-workspace-invite/) | Revoke a workspace's pending invite. Owners only. | `workspace`, `id` | `workspace:admin` | |
| 688 | | [`list_integrations`](/reference/api/integrations/list-integrations/) | The workspace's connections. Secrets are never returned. Members only. | `workspace` | `workspace:read` | |
| 689 | | [`connect_integration`](/reference/api/integrations/connect-integration/) | Connect Sentry, Datadog, a webhook, Jira or Linear, with `config` and `secret`. Owners only. | `workspace`, `provider` | `workspace:admin` | |
| 690 | | [`update_integration`](/reference/api/integrations/update-integration/) | Change one: its `name`, its `config` (replaced whole) or its `secret` (write-only, never returned). Owners only. | `workspace`, `id` | `workspace:admin` | |
| 691 | | [`disconnect_integration`](/reference/api/integrations/disconnect-integration/) | Remove it and its secrets. Owners only. | `workspace`, `id` | `workspace:admin` | |
| 692 | | [`test_integration`](/reference/api/integrations/test-integration/) | Check its credentials against the system it connects to. Owners only. | `workspace`, `id` | `workspace:admin` | |
| 693 | | [`list_projects`](/reference/api/projects/list-projects/) | Its projects you can see, by name: each with its `kind` and `kind_reason`, where it `runs` and its `production_url`, its repository and `root_dir`, and its `links`. | `workspace` | `repo:read` | |
| 694 | | [`get_project`](/reference/api/projects/get-project/) | One project, with what a person set (`setting`) and what detection decides (`detected`). | `workspace`, `project` | `repo:read` | |
| 695 | | [`update_project`](/reference/api/projects/update-project/) | Change its `name`, `description`, `root_dir`, `kind`, `runs`, `production_url`, `homepage`, `docs_url` or `links`; only what you give changes. `auto` leaves `kind` or `runs` to detection, null clears a link or goes back to the repository's, and `links` replaces its other links (at most 10). Maintain role or higher. | `workspace`, `project` | `repo:write` | |
| 696 | | [`list_pinned_projects`](/reference/api/pinned-projects/list-pinned-projects/) | Your pinned projects in it, in your order, each with its `position`. Your own: a personal token or an OAuth sign-in. | `workspace` | `account:read` | |
| 697 | | [`pin_project`](/reference/api/pinned-projects/pin-project/) | Pin a project you can see, at `position` (0 first) or at the end; at most 8 a workspace. Returns your pins. | `workspace`, `project` | `account:write` | |
| 698 | | [`unpin_project`](/reference/api/pinned-projects/unpin-project/) | Unpin it. Returns your pins. | `workspace`, `project` | `account:write` | |
| 699 | | [`reorder_pinned_projects`](/reference/api/pinned-projects/reorder-pinned-projects/) | Put your pins in a new order: `projects` names each pinned project's slug once. | `workspace`, `projects` | `account:write` | |
| 700 | | [`list_rulesets`](/reference/api/rules/list-workspace-rulesets/) | The workspace's own [rulesets](/guides/rules/). Members only. | `workspace` | `workspace:read` | |
| 701 | | [`get_ruleset`](/reference/api/rules/get-workspace-ruleset/) | One of them by `id`. Members only. | `workspace`, `id` | `workspace:read` | |
| 702 | | [`create_ruleset`](/reference/api/rules/create-workspace-ruleset/) | Create one, with `conditions.repository` choosing its repositories. Owners only. | `workspace` | `workspace:admin` | |
| 703 | | [`update_ruleset`](/reference/api/rules/update-workspace-ruleset/) | Change one. Owners only. | `workspace`, `id` | `workspace:admin` | |
| 704 | | [`delete_ruleset`](/reference/api/rules/delete-workspace-ruleset/) | Delete one. Owners only. | `workspace`, `id` | `workspace:admin` | |
| 705 | | [`rule_evaluations`](/reference/api/rules/list-workspace-rule-evaluations/) | How rules judged changes across its repositories, with insights. Members only. | `workspace` | `workspace:read` | |
| 706 | | [`get_token_policy`](/reference/api/personal-access-tokens/get-token-policy/) | Its [rules for personal access tokens](/guides/authentication/#a-workspaces-rules-for-tokens): `allow_tokens_for_this_workspace`, `allow_tokens_for_all_workspaces`, `require_approval`, `max_lifetime_days` and `forbid_no_expiry`. Members only. | `workspace` | `workspace:read` | |
| 707 | | [`set_token_policy`](/reference/api/personal-access-tokens/set-token-policy/) | Change them; fields left out stay. `max_lifetime_days` of 0 removes the limit. Owners only, as people. | `workspace` | `workspace:admin` | |
| 708 | | [`list_member_tokens`](/reference/api/personal-access-tokens/list-member-tokens/) | The personal access tokens of its members and outside collaborators that can reach it, with their owner, permissions, scopes, reach (`workspace`, `repository_selection`, `repositories`), last use, expiry, and whether each reaches it now (`reaches`, `blocked_by`). Never the token itself. Owners only, as people. | `workspace` | `access:read` | |
| 709 | | [`list_token_requests`](/reference/api/personal-access-tokens/list-token-requests/) | Tokens made for it that wait for approval. Owners only, as people. | `workspace` | `access:read` | |
| 710 | | [`review_token_request`](/reference/api/personal-access-tokens/review-token-request/) | Approve or deny one: `decision` is `approve` or `deny`, with an optional `reason` its owner is shown. Owners only, as people. | `workspace`, `id`, `decision` | `access:admin` | |
| 711 | | [`revoke_member_token`](/reference/api/personal-access-tokens/revoke-member-token/) | Take a member's token out of the workspace, with an optional `reason`. A token made for it stops reaching it; one made for all of its owner's workspaces keeps working elsewhere. Owners only, as people. | `workspace`, `id` | `access:admin` | |
| 712 | |
| 713 | ## `billing` |
| 714 | |
| 715 | A workspace's billing: its usage, its budget and its invoices. `usage` is |
| 716 | the default action. Amounts are whole millionths of a dollar (`_micros`), |
| 717 | or cents where a field says `_cents`. Members of the workspace read it, a |
| 718 | workspace's own token included. Changing the budget is for its owners, as |
| 719 | people: signed in or with a personal access token. A workspace's token |
| 720 | never changes billing, whatever its scopes, and no preset but full access |
| 721 | includes `billing:write`. See [usage and billing](/guides/usage-and-billing/). |
| 722 | |
| 723 | | Action | What it does | Required | Scope | |
| 724 | | --- | --- | --- | --- | |
| 725 | | [`usage`](/reference/api/billing/get-usage/) | Usage over `from` to `until` (UTC days, `until` included; the month so far when left out), narrowed by `products` and `projects`: `totals` and what paid for it, each day, and each product's meters with their daily amounts and split by project. `group_by` (`product`, `project` or `day`) adds `groups`. | `workspace` | `billing:read` | |
| 726 | | [`budget`](/reference/api/billing/get-budget/) | The monthly spend limit (`amount_micros`, or `automatic`), `spent_micros` this month, `max_amount_micros`, `alerts`, `pause_at_limit`, `webhook` and `state`. | `workspace` | `billing:read` | |
| 727 | | [`set_budget`](/reference/api/billing/set-budget/) | Change the limit (`amount_micros`, null for the automatic one), `alerts` (some of 50, 75, 90 and 100), `pause_at_limit` or `webhook`. Fields left out keep their value. Owners, as people. | `workspace` | `billing:write` | |
| 728 | | [`invoices`](/reference/api/billing/list-invoices/) | Every invoice (`invoices`, in cents), g1t's itemised usage invoices (`usage_invoices`), and what the next one comes to so far (`upcoming`). | `workspace` | `billing:read` | |
| 729 | | [`billing_details`](/reference/api/billing/get-billing-details/) | Who invoices are made out to, and the payment method on file as far as it is safe to show. | `workspace` | `billing:read` | |
| 730 | |
| 731 | ## `notifications` |
| 732 | |
| 733 | Your [notifications](/guides/notifications/): one thread per issue, pull request, workflow |
| 734 | on a branch or deployment, with why you were told (`reason`), and what you |
| 735 | subscribe to and watch. `list` is the default action. It is your own: a |
| 736 | personal access token or an OAuth sign-in can use it, a workspace's token |
| 737 | cannot. Name an issue or pull request by a thread's `id`, or by `repo` and |
| 738 | `number`. |
| 739 | |
| 740 | | Action | What it does | Required | Scope | |
| 741 | | --- | --- | --- | --- | |
| 742 | | [`list`](/reference/api/notifications/list-notifications/) | Your unread threads, latest first. With `all`, read ones too; `view` `saved` or `done` lists those instead. Filter by `reason`, `severity`, `participating`, `since`, `before` or `repo`. | None | `notifications:read` | |
| 743 | | [`get`](/reference/api/notifications/get-notification-thread/) | One thread, its last 10 activities, and your subscription to it. | `id` | `notifications:read` | |
| 744 | | [`mark_read`](/reference/api/notifications/mark-thread-read/) | Mark a thread read, or with `read` false, unread. | `id` | `notifications:write` | |
| 745 | | [`mark_all_read`](/reference/api/notifications/mark-notifications-read/) | Mark every thread read, or one repository's with `repo`. Threads with activity after `last_read_at` (now, when left out) stay unread. | None | `notifications:write` | |
| 746 | | [`done`](/reference/api/notifications/mark-thread-done/) | Move a thread to Done; new activity brings it back. With `done` false, move it back now. | `id` | `notifications:write` | |
| 747 | | [`save`](/reference/api/notifications/save-thread/) | Save a thread so it is kept, or with `saved` false, unsave it. | `id` | `notifications:write` | |
| 748 | | [`snooze`](/reference/api/notifications/snooze-thread/) | Hide a thread until `until` (RFC 3339). Leave `until` out to bring it back now. | `id` | `notifications:write` | |
| 749 | | [`subscription`](/reference/api/notifications/get-thread-subscription/) | Whether you are subscribed to an issue or pull request, or ignore it, and why. | `id`, or `repo` and `number` | `notifications:read` | |
| 750 | | [`subscribe`](/reference/api/notifications/set-thread-subscription/) | Subscribe (`subscribed`, true unless you say), unsubscribe (`subscribed` false), or ignore it (`ignored` true). | `id`, or `repo` and `number` | `notifications:write` | |
| 751 | | [`unsubscribe`](/reference/api/notifications/delete-thread-subscription/) | Unsubscribe until you comment or are mentioned. What is asked of you directly still reaches you. | `id`, or `repo` and `number` | `notifications:write` | |
| 752 | | [`watching`](/reference/api/notifications/get-repo-subscription/) | How you watch a repository: `participating`, `all`, `ignore` or `custom`, with `events`. | `repo` | `notifications:read` | |
| 753 | | [`watch`](/reference/api/notifications/set-repo-subscription/) | Watch a repository at a `level`, with `events` (`issues`, `pulls`, `deployments`, `security`) for `custom`. | `repo` | `notifications:write` | |
| 754 | | [`unwatch`](/reference/api/notifications/delete-repo-subscription/) | Go back to the default: only what you take part in or are mentioned in. | `repo` | `notifications:write` | |
| 755 | | [`watched`](/reference/api/notifications/list-watched-repos/) | The repositories you watch other than the default way. | None | `notifications:read` | |
| 756 | |
| 757 | ## `account` |
| 758 | |
| 759 | Who the token acts as and its workspaces, your email addresses, and |
| 760 | [invitations](/guides/authentication/#invites) to workspaces and |
| 761 | repositories waiting for you. `whoami` is the default |
| 762 | action, and needs no scope. A workspace's token cannot |
| 763 | use the email and invitation actions. An account that has not confirmed its |
| 764 | email address gets `403` from every tool until it does; see |
| 765 | [until you confirm](/guides/authentication/#until-you-confirm). |
| 766 | |
| 767 | | Action | What it does | Required | Scope | |
| 768 | | --- | --- | --- | --- | |
| 769 | | [`whoami`](/reference/api/accounts/whoami/) | Who the access token acts as, and the workspaces it can work in. `kind` is `user`, `workspace` or `agent`. | None | None | |
| 770 | | [`list_emails`](/reference/api/accounts/list-emails/) | Your email addresses and email settings. People only. | None | `account:read` | |
| 771 | | [`add_email`](/reference/api/accounts/add-email/) | Add an address; g1t emails it a code and a link to confirm it. | `email`, `password` | `account:write` | |
| 772 | | [`confirm_email`](/reference/api/accounts/confirm-email/) | Confirm an address with the six-digit code from its email. See [confirming your email address](/guides/authentication/#confirming-your-email-address). | `code` | `account:write` | |
| 773 | | [`remove_email`](/reference/api/accounts/remove-email/) | Remove an address; never the primary or the last confirmed one. | `email`, `password` | `account:write` | |
| 774 | | [`update_email_settings`](/reference/api/accounts/update-email-settings/) | Change `primary` or `backup` (with `password`), `private_email` or `block_private_pushes`. See [email addresses](/guides/authentication/#email-addresses). | None | `account:write` | |
| 775 | | [`list_workspace_invitations`](/reference/api/invites/list-invitations/) | The invitations to workspaces waiting for your answer, each with its `workspace`, the `role` it gives and who sent it. | None | `account:read` | |
| 776 | | [`accept_workspace_invitation`](/reference/api/invites/accept-invitation/) | Accept one; you join the workspace at once with its role. | `id` | `account:write` | |
| 777 | | [`decline_workspace_invitation`](/reference/api/invites/decline-invitation/) | Decline one; whoever sent it is told. | `id` | `account:write` | |
| 778 | | [`list_repository_invitations`](/reference/api/access/list-my-repo-invitations/) | The invitations to repositories waiting for your answer. | None | `account:read` | |
| 779 | | [`accept_repository_invitation`](/reference/api/access/accept-repo-invitation/) | Accept one; its role is yours at once. | `id` | `account:write` | |
| 780 | | [`decline_repository_invitation`](/reference/api/access/decline-repo-invitation/) | Decline one. | `id` | `account:write` | |
| 781 | |
| 782 | ## `artifact` |
| 783 | |
| 784 | A workspace's artifacts: its docs, and later its slides, designs and |
| 785 | dashboards. Each action runs as you: it finds and opens only what you can |
| 786 | open, and changes only what your role on it allows, whatever the token's |
| 787 | scope. Name one by its id (`fol_…`) or its link as `artifact_id`, and its |
| 788 | space by slug or id. Not workflow runs' artifacts, which are the |
| 789 | `workflow` tool's. Slides, designs and dashboards answer `422` saying they |
| 790 | are not here yet. A workspace's own token cannot use this tool. See |
| 791 | [artifacts](/guides/bring-your-own-agent/#artifacts). |
| 792 | |
| 793 | | Action | What it does | Required | Scope | |
| 794 | | --- | --- | --- | --- | |
| 795 | | [`list`](/reference/api/artifacts/list-workspace-artifacts/) | The artifacts you can open, most recently edited first, with your role on each. Narrow with `tab` (`all`, `yours`, `shared`), `kind`, `space`, `project` and `q`; page with `cursor`. `state` `trashed` lists what you can restore. | `workspace` | `artifacts:read` | |
| 796 | | [`search`](/reference/api/artifacts/search-workspace-artifacts/) | Search them by words and meaning; each hit has the passage that matched (`snippet`, `heading`). | `workspace`, `q` | `artifacts:read` | |
| 797 | | [`get`](/reference/api/artifacts/get-workspace-artifact/) | One artifact: kind, title, space, owner, your `viewer_role`, general access, whether it is private or stale, and `html_url`. | `workspace`, `artifact_id` | `artifacts:read` | |
| 798 | | [`read`](/reference/api/artifacts/get-workspace-artifact-content/) | Its content: a doc's Markdown, its top-level `blocks` with ids, and `can` (read, suggest, edit). | `workspace`, `artifact_id` | `artifacts:read` | |
| 799 | | [`versions`](/reference/api/artifacts/list-workspace-artifact-versions/) | Its saved versions, newest first, with who made each. | `workspace`, `artifact_id` | `artifacts:read` | |
| 800 | | [`access`](/reference/api/artifacts/get-workspace-artifact-access/) | Who can open it: its owner, who it is shared with and how, general access, and whether you may change it. | `workspace`, `artifact_id` | `artifacts:read` | |
| 801 | | [`templates`](/reference/api/artifacts/list-workspace-artifact-templates/) | Templates to start one from, built-in and the workspace's; narrow with `kind`. | `workspace` | `artifacts:read` | |
| 802 | | [`spaces`](/reference/api/artifacts/list-workspace-artifact-spaces/) | The spaces in your Artifacts sidebar, with your role in each. | `workspace` | `artifacts:read` | |
| 803 | | [`query_data`](/reference/api/artifacts/query-workspace-dataset/) | Run a dataset `query` as you, over what you can read. Answers that dashboards are not here yet until they ship. | `workspace`, `query` | `artifacts:read` | |
| 804 | | [`create`](/reference/api/artifacts/create-workspace-artifact/) | Make one from `markdown` or a `template_id`, in a `space`, under a `parent_id`, or in your Private. `kind` is `doc`; the others are not here yet. | `workspace` | `artifacts:write` | |
| 805 | | [`update`](/reference/api/artifacts/update-workspace-artifact/) | Change its `title` or `icon`, or move it to a `space` (`private` for your Private) or under a `parent_id`. | `workspace`, `artifact_id` | `artifacts:write` | |
| 806 | | [`edit`](/reference/api/artifacts/edit-workspace-artifact/) | Change its content: `markdown` with a `target` (`append`, `document`, a `section` by `heading`, or `blocks`). Made with the edit role; a suggestion with the comment role or `suggest_only`. `note` says why; `marks_current` clears the doc's possibly out of date mark when the change is made or accepted. | `workspace`, `artifact_id` | `artifacts:write` | |
| 807 | | [`trash`](/reference/api/artifacts/trash-workspace-artifact/) | Move it, and what is under it, to the trash; deleted for good after 30 days. | `workspace`, `artifact_id` | `artifacts:write` | |
| 808 | | [`restore`](/reference/api/artifacts/restore-workspace-artifact/) | Bring it back from the trash. | `workspace`, `artifact_id` | `artifacts:write` | |
| 809 | | [`restore_version`](/reference/api/artifacts/restore-workspace-artifact-version/) | Make an earlier version its content again, as a new version. | `workspace`, `artifact_id`, `version_id` | `artifacts:write` | |
| 810 | | [`share`](/reference/api/artifacts/set-workspace-artifact-access/) | Share it with a `username` or `team` at a `role` (`view`, `comment`, `edit`, `manage`, or `none` to take access away); set `general_access` and `general_role`, or `inherit`. Takes full access to it; where its space lets editors share, edit access shares up to `edit`. | `workspace`, `artifact_id` | `artifacts:admin` | |
| 811 | | [`purge`](/reference/api/artifacts/purge-workspace-artifact/) | Delete one in the trash for good. Takes full access to it. | `workspace`, `artifact_id` | `artifacts:admin` | |