Skip to content
Sign up

flagon-io/g1t

public
00

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp
893 linesCodeBlameRaw
1---
2title: g1t MCP tools
3description: The g1t MCP server's resource tools, each action they take with its required inputs and scope, and how to call them.
4---
5
6The MCP server at `https://mcp.g1t.sh` lets coding agents and chat apps
7work on g1t with the access you grant. It exposes 19 tools,
8one per kind of thing on g1t: `search`, `repository`, `work_item`,
9`pull_request`, `session`, `workflow`, `observability`, `package`, `secret`,
10`security`, `webhook`, `access`, `team`, `workspace`, `ai`, `billing`,
11`notifications`, `account` and `artifact`. Each tool takes an `action` that says what to do. Every
12action is the same operation as a route of the [REST API](/reference/api/),
13with the same inputs, permissions and results, so the two always agree.
14
15## Connect
16
17Choose your client in [Connect an AI client](/guides/bring-your-own-agent/)
18for coding agents, ChatGPT, Claude, Grok, Open WebUI, LibreChat and other
19MCP clients. The guide remembers your choice.
20
21The [Claude Code plugin](/guides/claude-code-plugin/) adds the server and
22records sessions through hooks. The [Codex plugin](/guides/bring-your-own-agent/#codex-marketplace)
23adds the server and a skill for coordinating work and recording session summaries.
24Use either the plugin or a standalone server connection for a given client
25to avoid duplicate tools.
26
27The server speaks MCP over streamable HTTP, and answers every request with
28JSON. Every call needs to be signed in, in one of two ways:
29
30- **OAuth.** A client that supports MCP authorization needs only the URL.
31 An unauthenticated request is answered with `401` and a pointer to
32 `https://mcp.g1t.sh/.well-known/oauth-protected-resource`; the client
33 registers itself and sends you to your browser to approve it. See
34 [signing in with OAuth](/guides/authentication/#signing-in-with-oauth).
35- **An access token.** Send `Authorization: Bearer g1t_…` with an
36 [access token](/guides/authentication/#access-tokens).
37
38Opening [mcp.g1t.sh](https://mcp.g1t.sh) in a browser shows the server's
39card: what it is, how to connect, and every tool with its actions, the
40operation and scope of each, and its input schema.
41
42## How tools and actions work
43
44Call a tool with `tools/call`, its name, and `arguments` that hold the
45`action` and that action's inputs:
46
47```json
48{
49 "jsonrpc": "2.0",
50 "id": 1,
51 "method": "tools/call",
52 "params": {
53 "name": "work_item",
54 "arguments": { "action": "get", "workspace": "flagon-io", "number": 42 }
55 }
56}
57```
58
59- `action` is required, except on three tools that have a default:
60 `search` runs `code`, `notifications` runs `list`, and `account` runs
61 `whoami`, when it is left out.
62- The input schema that `tools/list` returns is one flat object: `action`,
63 then every field any of the tool's actions takes. The `action` field's
64 description lists each action with the fields it needs, such as
65 `get (workspace, number): One work item with comments and its pull requests.`
66- The server card at `https://mcp.g1t.sh` has each tool's schema keyed by
67 action: a `oneOf` with one branch per action and its required fields.
68 `tools/list` does not use `oneOf`, because many clients refuse a tool
69 whose schema has one at its top level.
70- A call without one of its action's required fields is not run. It
71 returns an error result naming them, such as `work_item.get needs number.`
72 A call without an action on a tool that has no default, or with an
73 action the tool does not have, returns an error result that lists the
74 tool's actions.
75- A tool name the server does not know is a JSON-RPC error, `-32602`.
76
77### Results
78
79A result is the operation's answer as JSON text, with `snake_case` fields,
80as the REST API returns it. Each person in it has a lowercased `username`
81and a `display_username`, the case they chose
82([Usernames](/reference/api/#requests-and-responses)):
83
84```json
85{
86 "jsonrpc": "2.0",
87 "id": 1,
88 "result": {
89 "content": [{ "type": "text", "text": "{\n \"number\": 42,\n \"title\": \"Retry failed webhook deliveries\",\n …\n}" }],
90 "isError": false
91 }
92}
93```
94
95An operation that fails returns its message as the result, with `isError`
96set to `true`, so the agent can read it and act on it.
97
98### Examples
99
100Start a draft pull request for work item 42. The answer holds the git remote of
101the pull request's own fork to push to:
102
103```json
104{
105 "jsonrpc": "2.0",
106 "id": 2,
107 "method": "tools/call",
108 "params": {
109 "name": "pull_request",
110 "arguments": { "action": "create", "repo": "flagon-io/hello", "item": 42, "agent": "claude-code" }
111 }
112}
113```
114
115Search code across g1t, with the default action:
116
117```json
118{
119 "jsonrpc": "2.0",
120 "id": 3,
121 "method": "tools/call",
122 "params": {
123 "name": "search",
124 "arguments": { "query": "parse_query language:rust repo:flagon-io/hello" }
125 }
126}
127```
128
129The same call with `curl` and an access token:
130
131```sh
132curl https://mcp.g1t.sh \
133 -H "Authorization: Bearer $G1T_TOKEN" \
134 -H "Content-Type: application/json" \
135 -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search", "arguments": {"query": "parse_query language:rust repo:flagon-io/hello"}}}'
136```
137
138## What you see depends on your token
139
140Each action needs one [scope](/guides/authentication/#scopes), shown in the
141tables below; `whoami` needs none. A scope is one level of one of a token's
142[permissions](/guides/authentication/#permissions): `work:write` is
143Work: read and write. `tools/list` shows a token only what its
144permissions allow:
145
146- The `action` field lists only the actions the token may use, and the
147 schema has only their fields.
148- A tool with none of its actions allowed is left out.
149- A call to an action the token's scopes do not allow is refused with an
150 error result such as
151 `This access token needs the work:write scope to use open_work_item.`
152
153For example, a token with only `work:write` sees `work_item` (its `list` and
154`get` too, since `write` includes `read`); `workspace` with its label and
155milestone actions; `repository` with its `work` list and commit comments;
156`search` with `ticket`; and `account` with `whoami`. A token with the
157[Read only preset](/guides/authentication/#presets) sees only the reading
158actions of each tool.
159
160What a token may do is also bounded by the role of whoever it acts as, and
161by [where it reaches](/guides/authentication/#where-a-token-reaches): all
162of their workspaces, one, or none. See
163[scopes](/guides/authentication/#scopes).
164
165A token with every permission at its highest level, such as one from
166signing in from a tool, and an OAuth sign-in made before applications had
167scopes, see every tool.
168
169### Annotations
170
171Each listed tool carries MCP annotations, worked out from the actions the
172token can see. Clients use them to decide when to ask you before a call.
173
174| Annotation | Value |
175| --- | --- |
176| `title` | The tool's name for people, such as `Pull requests`. |
177| `readOnlyHint` | `true` when every action shown only reads. |
178| `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 or changing an integration, removing or changing an AI provider, 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. |
179| `idempotentHint` | The same as `readOnlyHint`. |
180| `openWorldHint` | Always `false`. |
181
182So for a read-only token every tool is read-only, and for a token that can
183merge, `pull_request` is destructive.
184
185## Earlier tool names
186
187Before resource tools, the server had one tool per operation, named after
188the operation: `create_pull_request`, `record_session`,
189`mark_pull_request_ready` and so on. `tools/list` no
190longer lists them, but `tools/call` still answers them for a deprecation
191period, so clients set up with them keep working. Move to the resource
192tool and its action: the tables below give each, and each page of the
193[API reference](/reference/api/) names the tool and action for its
194operation. `get_issue` went with issues: use `work_item` with
195`"action": "get"` (see [issues became work items](/work/from-issues/)).
196
197| Earlier name | Now |
198| --- | --- |
199| `create_pull_request` | `pull_request` with `"action": "create"` |
200| `record_session` | `pull_request` with `"action": "record_session"` |
201| `mark_pull_request_ready` | `pull_request` with `"action": "ready"` |
202| `get_pull_request` | `pull_request` with `"action": "get"` |
203| `search` | `search`, with `"action": "code"` or none |
204| `get_context` | `search` with `"action": "ticket"` |
205| `whoami` | `account`, with `"action": "whoami"` or none |
206
207## Conventions
208
209- `repo` is always `owner/name`, such as `"flagon-io/hello"`.
210- `workspace` is a workspace's slug, such as `"flagon-io"`.
211- `number` names a work item or a pull request. The two share one sequence
212 per workspace, so a number names exactly one of them in it. Pull requests
213 opened before work items keep their older numbers, so give `repo` with
214 the number of a pull request.
215- Inputs are `snake_case`. Results are JSON, with `snake_case` fields, as
216 the REST API returns them.
217- Reading a public repository needs no sign-in through the API. Through MCP,
218 every call needs to be signed in.
219- Each token may make 1,000 requests a minute to the MCP server, apart from
220 its REST API calls. Past that, the request is answered `429` with a
221 `Retry-After` header and a `rate_limited` error. See
222 [rate limits](/reference/rate-limits/).
223
224The tables below list each action's required inputs. Optional inputs are
225in the tool's schema, which `tools/list` returns, and on the action's page
226in the [API reference](/reference/api/), which each action links to.
227
228## `search`
229
230Find things. `code`, the default, searches all of g1t you can see:
231repositories, code on default branches, work items, pull requests and people.
232`ticket` reads an item from a connected tracker. See
233[search and Explore](/guides/search/) for the query syntax.
234
235| Action | What it does | Required | Scope |
236| --- | --- | --- | --- |
237| [`code`](/reference/api/search/search/) | Search all of g1t: repositories, code on default branches, work items, 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:item`, `is:pr`, `author:` and `label:`. `type` is `repositories`, `code`, `items`, `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` |
238| [`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` | `work:read` |
239
240## `repository`
241
242Repositories: find, read and create them, change their settings,
243see and dismiss their [security alerts](/guides/security/), read what their
244default branch says (languages, contributors, license), star them,
245publish [releases](/guides/releases/) and
246[comment on their commits](/guides/pull-requests/#commit-comments). Deleting, purging
247and changing visibility need `confirm`, the repository's full name typed
248out.
249
250| Action | What it does | Required | Scope |
251| --- | --- | --- | --- |
252| [`list`](/reference/api/repositories/list-repos/) | Repositories you can see, optionally filtered by `query`. | None | `repo:read` |
253| [`get`](/reference/api/repositories/get-repo/) | One repository's details. | `repo` | `repo:read` |
254| [`commits`](/reference/api/repositories/list-commits/) | A branch's commits, newest first, each with its `sha`, `message`, `author` (`name` as git recorded it, and `username` when the author's address is a g1t account's; never the address), `authored_at` and `html_url`; `ref` names another branch, tag or commit, `limit` is 30 unless you say (at most 100). With `path`, only the commits that changed that file or directory (its history), newest first, with `last_changed` (the newest) and `complete` (false when a long history was not walked to its start in time). | `repo` | `code:read` |
255| [`commit_comments`](/reference/api/commit-comments/list-commit-comments/) | A commit's comments (`sha`), oldest first: on the whole commit, or on a `line` of a `path` it changed. | `repo`, `sha` | `repo:read` |
256| [`list_commit_comments`](/reference/api/commit-comments/list-repo-commit-comments/) | All the repository's commit comments, newest first, 30 a `page`. | `repo` | `repo:read` |
257| [`comment_on_commit`](/reference/api/commit-comments/create-commit-comment/) | Comment on commit `sha`, or with `path` and `line` on one line of a file it changed. Refused where the repository turned commit comments off. | `repo`, `sha`, `body` | `work:write` |
258| [`edit_commit_comment`](/reference/api/commit-comments/update-commit-comment/) | Change a commit comment's `body`, by `comment_id`. Its author only. | `repo`, `comment_id`, `body` | `work:write` |
259| [`delete_commit_comment`](/reference/api/commit-comments/delete-commit-comment/) | Delete a commit comment by `comment_id`. Its author, or the Maintain role. | `repo`, `comment_id` | `work:write` |
260| [`contents`](/reference/api/repositories/get-contents/) | What it holds at `path` (the root when left out) at `ref` (the default branch when left out): a file's `text` (null for a binary one; at most 200,000 characters), or a directory's `entries` and its README. | `repo` | `code:read` |
261| [`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` |
262| [`zipball`](/reference/api/repositories/download-zipball-archive/) | The same as a `.zip`. | `repo` | `code:read` |
263| [`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`). `description` becomes its [project's](/guides/projects/), as a repository has none of its own. `workspace` may be left out if you belong to exactly one. It is private unless `private` is false (or `visibility` is `public`); the [REST API](/reference/api/repositories/create-repo/) makes one public unless `private` is true. `deploy: true` turns its [deployments](/guides/deployments/#without-the-site) on once it is made: the answer has `deployments` with `production_url`, or `deploy_error` saying why not (the repository is made either way). | `name` | `repo:create`, which `repo:write` includes and the [Agent preset](/guides/authentication/#presets) gives |
264| [`update`](/reference/api/repositories/update-repo/) | Change its `website`, `topics` and `default_branch`, whether its default branch is `protected`, whether it is `private`, and whether a private repository may be forked (`allow_forking`). Maintain role; `protected`, `private`, `allow_forking` and `default_branch` need Admin, and `private` the [member privileges](/guides/workspaces/#member-privileges) unless you are an owner. | `repo` | `repo:write` |
265| [`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` |
266| [`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` |
267| [`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` |
268| [`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` |
269| [`get_ruleset`](/reference/api/rules/get-repo-ruleset/) | One ruleset by `id`. | `repo`, `id` | `repo:read` |
270| [`create_ruleset`](/reference/api/rules/create-repo-ruleset/) | Create one: `ruleset_name`, `enforcement`, `target`, `conditions`, `bypass_actors`, `rules`. Admin role. | `repo` | `repo:admin` |
271| [`update_ruleset`](/reference/api/rules/update-repo-ruleset/) | Change one; fields left out stay. Admin role. | `repo`, `id` | `repo:admin` |
272| [`delete_ruleset`](/reference/api/rules/delete-repo-ruleset/) | Delete one. Admin role. | `repo`, `id` | `repo:admin` |
273| [`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` |
274| [`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` |
275| [`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` |
276| [`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` |
277| [`work`](/reference/api/work-items/list-repo-work-items/) | The work items linked to it, in any role or in `role` (`origin`, `target` or `touched`), by `state`, `label`, `milestone` and `assignee`: the workspace's work list filtered to it. Read only: open one with `work_item` `create`. | `repo` | `work:read` |
278| [`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` |
279| [`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` |
280| [`license`](/reference/api/repository-insights/get-license/) | The license its `LICENSE` file holds: `spdx_id`, `name`, `path`. | `repo` | `repo:read` |
281| [`stargazers`](/reference/api/stars/list-stargazers/) | Who starred it, newest first, 100 a `page`. | `repo` | `repo:read` |
282| [`starred`](/reference/api/stars/check-starred/) | Whether you starred it, and how many have. | `repo` | `account:read` |
283| [`star`](/reference/api/stars/star-repo/) | Star it. People only. | `repo` | `account:write` |
284| [`unstar`](/reference/api/stars/unstar-repo/) | Take your star back. | `repo` | `account:write` |
285| [`list_starred`](/reference/api/stars/list-starred/) | Repositories you starred that you can still see. | None | `account:read` |
286| [`list_releases`](/reference/api/releases/list-releases/) | Its [releases](/guides/releases/), newest first; drafts only for the Write role. | `repo` | `repo:read` |
287| [`latest_release`](/reference/api/releases/get-latest-release/) | The newest published release that is neither a draft nor a prerelease. | `repo` | `repo:read` |
288| [`get_release`](/reference/api/releases/get-release/) | One release by `id`. | `repo`, `id` | `repo:read` |
289| [`get_release_by_tag`](/reference/api/releases/get-release-by-tag/) | The release of a `tag`. | `repo`, `tag` | `repo:read` |
290| [`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` |
291| [`update_release`](/reference/api/releases/update-release/) | Change its `release_name`, `body`, `draft` or `prerelease`. Write role. | `repo`, `id` | `repo:write` |
292| [`delete_release`](/reference/api/releases/delete-release/) | Delete a release; its tag stays. Write role. | `repo`, `id` | `repo:write` |
293| [`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` |
294| [`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` |
295| [`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` |
296| [`rename`](/reference/api/repositories/rename-repo/) | Give it a new name in its workspace; the old address redirects. Admin role. | `repo`, `name` | `repo:admin` |
297| [`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` |
298| [`fork`](/reference/api/repositories/fork-repo/) | [Fork it](/guides/forking-repositories/) into `workspace` (your personal workspace when left out), as `name`; `default_branch_only` (true unless you say) copies the default branch alone. Only its code is copied, and its project starts with the parent project's description; workflows start off. A private repository only when its admins allow forking. | `repo` | `repo:write` |
299| [`forks`](/reference/api/repositories/list-forks/) | Its forks you can see, newest first, each with `parent`; `limit` at most 100. | `repo` | `repo:read` |
300| [`sync_fork`](/reference/api/repositories/sync-fork/) | Bring a fork's `branch` (its default branch when left out) up to date with its parent: `status` is `up_to_date`, `fast_forwarded`, `merged` or `conflicted` (with `conflicts`), with `behind` and `ahead`. Write role on the fork. | `repo` | `repo:write` |
301| [`detach_fork`](/reference/api/repositories/detach-fork/) | Make a fork an ordinary repository with no parent, whose visibility can then change. It cannot be attached again. Admin role. | `repo` | `repo:admin` |
302| [`archive`](/reference/api/repositories/archive-repo/) | Make it read-only: pushes and merges are refused, its pull requests and the work items filed in it are locked, and workflows stop. Admin role. | `repo` | `repo:admin` |
303| [`unarchive`](/reference/api/repositories/unarchive-repo/) | Make it writable again. Admin role. | `repo` | `repo:admin` |
304| [`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` |
305| [`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` |
306| [`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` |
307| [`restore`](/reference/api/repositories/restore-repo/) | Bring a deleted repository back at the path it had. Owners only. | `repo` | `repo:admin` |
308| [`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` |
309| [`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` |
310| [`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` |
311| [`reopen_alert`](/reference/api/security/reopen-security-alert/) | Open a dismissed alert again. The same roles as dismissing. | `repo`, `id` | `repo:admin` |
312| [`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 work `item`, the `decisions` recorded on the pull request, and the `sessions` entries behind the commit. | `repo`, `path`, `line` | `code:read` |
313
314`update_settings` takes `required_checks` (at most 20 names),
315`required_approvals`, `allow_ignoring_checks`, `require_up_to_date`,
316`auto_merge`, `merge_queue` and `require_code_owner_review`, which holds a
317merge until the [code owners](/guides/codeowners/) of every file it changes
318approve. See
319[required status checks](/guides/pull-requests/#required-status-checks).
320It also takes the repository's [merge, commit and work item settings](/guides/managing-repositories/#settings):
321the merge methods it allows (`allow_merge_commit`, `allow_squash_merge`,
322`allow_rebase_merge`, `allow_fast_forward`) and `default_merge_method`,
323`merge_commit_message`, `squash_commit_message` and their templates,
324`suggest_updating_branches`, `allow_auto_merge`, `delete_branch_on_merge`,
325`require_web_commit_sign_off`, `allow_commit_comments`,
326`auto_close_items` and `has_work_items`.
327`update` with `private`, `default_branch`, `allow_forking` or
328`max_ref_updates` also needs `repo:admin`.
329
330See [managing a repository](/guides/managing-repositories/) for what each
331of these changes, and what refuses it, and
332[access and roles](/guides/access-and-roles/) for the role each needs.
333
334## `work_item`
335
336[Work items](/work/work-items/): what should change, a feature, a bug or
337a chore. A work item belongs to a workspace and links the repositories it
338starts in and lands in. Each action takes `workspace` and the item's
339`number`; `repo` is optional: the origin of a new work item, a filter, or
340in place of `workspace`, which is then the repository's. Before working on
341one, `work` gives everything about it, and `claim` says you are on it; see
342[claims and dependencies](/work/claims-and-dependencies/). Work items and pull
343requests share numbers in a workspace; a pull request's comments, labels
344and reactions are on the [`pull_request`](#pull_request) tool. `resolve`
345says which of the two a `#N` names. `attach` uploads an image, such as a
346screenshot, and gives the Markdown that shows it in a description or a
347comment.
348
349| Action | What it does | Required | Scope |
350| --- | --- | --- | --- |
351| [`list`](/reference/api/work-items/list-work-items/) | Work items, newest first, by `state`, `label`, `milestone` (its number), `assignee`, and `repo` (the items linked to it, in any role). | `workspace` or `repo` | `work:read` |
352| [`get`](/reference/api/work-items/get-work-item/) | A work item: description (which may say what done means, under **Definition of done**), labels, comments, its `repos` with their roles and whether each `landed`, its `resolutions`, and every pull request made for it. | `workspace`, `number` | `work:read` |
353| [`create`](/reference/api/work-items/open-work-item/) | Open a work item, with `body`, `labels`, `milestone`, `repo` (its origin) and `targets` (the repositories it should land in). A label the workspace lacks is created for someone with the Write role. Say what done means in `body`, under a **Definition of done** heading. | `workspace` or `repo`, `title` | `work:write` |
354| [`update`](/reference/api/work-items/update-work-item/) | Change its title, body, labels, milestone, assignees or `blocked_by` (the work items 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 work item itself, something not a work item of the workspace, or makes a cycle is refused. | `workspace`, `number` | `work:write` |
355| [`links`](/reference/api/work-items/list-work-item-links/) | The repositories it is linked to: its origin, then its targets, then those it touched, each with its `role`, its `legacy_number` (the issue number it had in its origin) and whether it `landed`; `missing` lists the targets it has not landed in yet. | `workspace`, `number` | `work:read` |
356| [`link`](/reference/api/work-items/link-work-item/) | Link a repository of the workspace in a `role`: `target` (the default) or `touched`; linking one already linked changes its role. An origin cannot be given. Triage role. | `workspace`, `number`, `repo` | `work:write` |
357| [`unlink`](/reference/api/work-items/unlink-work-item/) | Unlink a target or a touched repository. Its origin stays. Triage role. | `workspace`, `number`, `repo` | `work:write` |
358| [`labels`](/reference/api/work-items/list-work-item-labels/) | The labels a work item carries, with their colors. | `workspace`, `number` | `work:read` |
359| [`add_labels`](/reference/api/work-items/add-work-item-labels/) | Add `labels` to it, keeping the ones it has. | `workspace`, `number`, `labels` | `work:write` |
360| [`set_labels`](/reference/api/work-items/set-work-item-labels/) | Replace its labels with `labels`. | `workspace`, `number`, `labels` | `work:write` |
361| [`remove_labels`](/reference/api/work-items/remove-work-item-labels/) | Take `label`, or several `labels`, off it; with neither, all of them. | `workspace`, `number` | `work:write` |
362| [`close`](/reference/api/work-items/close-work-item/) | Close it as `completed` or `not_planned`; with `commit` and `repo`, a commit already on that repository's default branch that names it after a closing keyword lands it there, as its push would have. | `workspace`, `number` | `work:write` |
363| [`reopen`](/reference/api/work-items/reopen-work-item/) | Reopen a closed work item. Its resolutions are cleared. | `workspace`, `number` | `work:write` |
364| [`comment`](/reference/api/work-items/add-work-item-comment/) | Comment on it, in Markdown. | `workspace`, `number`, `body` | `work:write` |
365| [`edit_comment`](/reference/api/work-items/edit-work-item-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. | `workspace`, `comment_id`, `body` | `work:write` |
366| [`delete_comment`](/reference/api/work-items/delete-work-item-comment/) | Delete a comment, by its id. Your own, or anyone's with the Maintain role or higher. | `workspace`, `comment_id` | `work:write` |
367| [`react`](/reference/api/work-items/react-to-work-item/) | React with an emoji (`content`: `+1`, `-1`, `laugh`, `hooray`, `confused`, `heart`, `rocket` or `eyes`) to its description, or with `comment_id` to one of its comments; `remove` takes it back. | `workspace`, `number`, `content` | `work:write` |
368| [`decisions`](/reference/api/work-items/list-work-item-decisions/) | The [decision records](/guides/why-blame/#decision-records) on it and on each of its pull requests, in any repository, oldest first. | `workspace`, `number` | `work:read` |
369| [`attach`](/reference/api/work-items/upload-work-item-attachment/) | Upload an image to show in its description or in a comment on it, kept by the work item, so one filed with no repository takes images too: `data` base64-encoded, `name` its file name. PNG, JPEG, GIF or WebP of at most 10 MB, by its bytes (`413` `too_large`, `415` `unsupported_type` otherwise). Returns `id`, `url`, `content_type`, `size` and `markdown` (`![name](url)`) to paste into a `body`. The file travels in the tool call, so keep it small (a few hundred KB); `g1t work comment --attach FILE` sends one from disk. Anyone who may comment on it may. | `workspace`, `number`, `name`, `data` | `work:write` |
370| [`import`](/reference/api/work-items/import-work-items/) | Open a work item from a Jira, Linear or Sentry item, linked to it. | `workspace`, `reference` | `work:write` |
371| [`resolve`](/reference/api/work-items/resolve-ref/) | What `#number` names where it is written: in `repo`, a pull request of it, then a work item filed there under that old issue number, then the workspace's work item, then a pull request of another of its repositories; in a `workspace` alone ([`GET /workspaces/{workspace}/refs/{number}`](/reference/api/work-items/resolve-ref-for-workspace/)), its work item, else its pull request. Answers `kind` `work_item`, `pull` or `none`. | `workspace` or `repo`, `number` | `work:read` |
372| [`work`](/reference/api/work-items/get-work/) | Everything to pick a work item up: its definition of done, each repository with its required checks, its repositories with what landed where and which targets are still missing, suggested targets (each with `why`), active claims, sessions, pull requests (checks, mergeability, overlaps, queue place), what it is blocked by and blocks, decisions, and its recent coordination events. | `workspace`, `number` | `work:read` |
373| [`claim`](/reference/api/work-items/claim-work-item/) | Say you are working on an open work item: 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. With `title` (and `body`) instead of `number`, it [opens the work item first](/reference/api/work-items/claim-new-work-item/), claims it, attaches the `session_id` session to it, and returns it as `item`. | `workspace`, and `number` or `title` | `work:write` |
374| [`release`](/reference/api/work-items/release-claim/) | Give up your claim, with an optional `reason`. | `workspace`, `number` | `work:write` |
375| [`handoff`](/reference/api/work-items/hand-off-work-item/) | End your claim as handed off, `to` someone or anyone, with a `note` on where the work stands. | `workspace`, `number`, `note` | `work:write` |
376| [`list_claims`](/reference/api/work-items/list-claims/) | Claims on the workspace's work items, newest first: active unless `state` says otherwise, `item` for one, `repo` for one repository's. | `workspace` | `work:read` |
377
378## `pull_request`
379
380Pull requests: start a change for a work item, record your session,
381comment and react, attach images, mark it ready, review, update its branch, and merge by a merge commit, a squash, a
382rebase or a fast-forward, now or with auto-merge. Read `overlaps` and
383`behind` on `get` before going far.
384
385| Action | What it does | Required | Scope |
386| --- | --- | --- | --- |
387| [`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` |
388| [`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 work item, 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` |
389| [`changes`](/reference/api/pull-requests/get-pull-request-changes/) | The files it changes, with line-by-line diffs. | `repo`, `number` | `pull_requests:read` |
390| [`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 (with `head_repo`, a branch of your fork). Give `item`, the work item's number in the workspace, whenever there is one: the repository becomes touched on it. It merges into the default branch unless `base` names another. | `repo` | `pull_requests:write` |
391| [`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` |
392| [`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` |
393| [`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` |
394| [`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` |
395| [`list_decisions`](/reference/api/decisions-and-why/list-decisions/) | The decision records on a pull request, oldest first, each with its `kind`, `confidence` (`claimed`, `tested` or `approved`), `summary` and `evidence`. A work item's, with its pull requests', are `work_item` `decisions`. | `repo`, `number` | `pull_requests:read` |
396| [`comment`](/reference/api/pull-requests/add-comment/) | Comment on it, in Markdown; with `path` and `line`, on one line of its change. | `repo`, `number`, `body` | `pull_requests:write` |
397| [`edit_comment`](/reference/api/pull-requests/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` | `pull_requests:write` |
398| [`delete_comment`](/reference/api/pull-requests/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` | `pull_requests:write` |
399| [`react`](/reference/api/pull-requests/react/) | React with an emoji (`content`) to its description, or with `comment_id` to one of its comments; `remove` takes it back. | `repo`, `number`, `content` | `pull_requests:write` |
400| [`attach`](/reference/api/work-items/upload-attachment/) | Upload an image to show in a pull request's description, its summary or a comment, kept by the repository: `data` base64-encoded, `name` its file name. As the `work_item` tool's `attach` otherwise; `g1t attach FILE` sends one from disk. Anyone who may comment on the repository may. | `repo`, `name`, `data` | `work:write` |
401| [`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` |
402| [`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` |
403| [`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` |
404| [`remove_requested_reviewers`](/reference/api/pull-requests/remove-requested-reviewers/) | Stop asking them. Reviews they gave stay. | `repo`, `number` | `pull_requests:write` |
405| [`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` |
406| [`close`](/reference/api/pull-requests/close-pull-request/) | Close it without merging. | `repo`, `number` | `pull_requests:write` |
407| [`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` |
408| [`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. `merge_method` is `merge`, `squash`, `rebase` or `fast_forward` (the repository's default when left out); `commit_title` and `commit_message` write a merge or squash commit's message; `sha` refuses if its head moved; `delete_branch` deletes its branch once merged. `bypass_rules` merges past rules a ruleset lets you bypass, and `ignore_checks` past required checks where the repository allows it. Into the default branch, it lands the repository on the work items in `closes`, and closes each one that has no target left to land; those in `parts` are only linked. Write role. | `repo`, `number` | `pull_requests:write` |
409| [`merge_options`](/reference/api/pull-requests/get-pull-request-merge-options/) | How it may merge now: `methods`, `default_method`, each method's default commit message, whether it is `behind` or `can_fast_forward`, and whether you may turn on auto-merge. | `repo`, `number` | `pull_requests:read` |
410| [`update_branch`](/reference/api/pull-requests/update-pull-request-branch/) | Bring its branch up to date with its base: `update_method` `merge` (the default) or `rebase`; `expected_head_sha` refuses if its head moved. `outcome` is `updated`, `up_to_date` or `needs_agent` (nothing pushed; the same lines changed on both sides). | `repo`, `number` | `pull_requests:write` |
411| [`enable_auto_merge`](/reference/api/pull-requests/enable-pull-request-auto-merge/) | Merge it on its own, as you, once its checks, reviews and rules allow, by `merge_method` with `commit_title` and `commit_message`. Write role, or its author. | `repo`, `number` | `pull_requests:write` |
412| [`disable_auto_merge`](/reference/api/pull-requests/disable-pull-request-auto-merge/) | Turn its auto-merge off. | `repo`, `number` | `pull_requests:write` |
413| [`delete_branch`](/reference/api/pull-requests/delete-pull-request-head-branch/) | Delete a merged or closed pull request's branch; `restore_branch` brings it back. Write role. | `repo`, `number` | `pull_requests:write` |
414| [`restore_branch`](/reference/api/pull-requests/restore-pull-request-head-branch/) | Make its deleted branch again at its head commit. Write role. | `repo`, `number` | `pull_requests:write` |
415| [`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` |
416
417`record_session` takes a list of `entries`, each with a `kind` (`prompt`,
418`message`, `tool_call`, `tool_result` or `note`) and `text`, and `tool` for
419tool entries. See [sessions and why-blame](/guides/why-blame/) and the
420[merge queue](/guides/merge-queue/). g1t records `integration_failure`,
421`integration_passed`, `approval` and `merge` decisions itself; see
422[decision records](/guides/why-blame/#decision-records).
423
424## `session`
425
426Your harness's session on a repository, so others see who is working on
427what. Start one per run of your harness, heartbeat it, record what it does,
428and end it. See [sessions](/guides/sessions/#record-a-session).
429
430| Action | What it does | Required | Scope |
431| --- | --- | --- | --- |
432| [`start`](/reference/api/sessions/start-session/) | Start a session: `harness` (`claude_code`, `claude_managed_agents`, `codex`, `cursor`, `copilot` or `other`), and `harness_session_id`, which makes starting again return the same session. `item` (a work item of the repository's workspace), `pull`, `branch`, `title` and `head_commit` as you know them. A subagent gives `parent_id`, `agent_type`, `task` and `prompt`, and starts on its parent's work item and branch. | `repo`, `harness` | `pull_requests:write` |
433| [`update`](/reference/api/sessions/update-session/) | A heartbeat, and renews the session's claims; with fields, attaches an `item` or `pull`, or sets `branch`, `head_commit`, `title`, or a subagent's `task`, `prompt`, `model` or `result`; `usage` reports its token usage so far, per model, from which g1t estimates `cost_usd`. | `repo`, `id` | `pull_requests:write` |
434| [`record`](/reference/api/sessions/record-session-entries/) | Record up to 200 `entries`, each with `kind` and `text` (`skill` for a skill used, by name), `tool` for tools, and a `key` that makes recording it again a no-op; and `touched`, what it touched (`file`, `commit`, `branch`, `pull`, `item`), which ties it to pull requests and work items and tells sessions on the same files of each other. | `repo`, `id` | `pull_requests:write` |
435| [`end`](/reference/api/sessions/end-session/) | End it, with an optional `reason` and `result` (what it reported). Its subagents still going end with it. | `repo`, `id` | `pull_requests:write` |
436| [`get`](/reference/api/sessions/get-session/) | A session and its entries (`after` pages through them), its subagents (`children`), what they touched, the work items and pull requests they worked on (`links`) and the skills used. With [`workspace`](/reference/api/sessions/get-workspace-session/) and `id` instead of `repo`, a session of any of the workspace's repositories, with its `repo`. | `repo` or `workspace`, `id` | `pull_requests:read` |
437| [`list`](/reference/api/sessions/list-sessions/) | A repository's sessions, most recently heard from first, by `state` (`active`, `idle`, `ended`), `item` or `pull` (any session tied to it), or `path` (a file touched); `subagents` lists each tree whole. With [`workspace`](/reference/api/sessions/list-workspace-sessions/) instead of `repo`, the sessions of every repository of the workspace you can read, as [Sessions](/work/sessions/) shows them: by `state` (`live`, `recent`, `ended`), `kind` (`harness`, `hosted`, `agent`, `recorded`), `harness`, `person`, `repo`, `item`, `subagents` and `limit`, with each repository's merge `queue`, what `landed` and the `repos` covered. | `repo` or `workspace` | `pull_requests:read` |
438| [`dispatch`](/reference/api/sessions/start-agent-session/) | Start work on an `item` (or a new work item from `title` and `body`) in a session on the person's own Claude: a Claude Managed Agents session on the workspace's Anthropic account, recorded here, or with `handoff` a Claude Code command line to run. `mode` is `plan`, `implement` or `review`; `instruction` adds to it. | `repo` | `pull_requests:write` |
439
440## `workflow`
441
442Workflows in `.g1t/workflows/`: their runs, jobs and logs, and running,
443cancelling or rerunning them; their artifacts; checks on commits (statuses, check runs and
444check suites, a workflow job being a check run); a repository's deployments
445and environments, with their protection rules; approving runs and
446deployments; and the self-hosted runners workflows run on. See
447[GitHub Actions](/guides/actions/), [Checks](/guides/checks/),
448[Deployments API](/guides/deployments-api/) and
449[self-hosted runners](/guides/self-hosted-runners/).
450
451| Action | What it does | Required | Scope |
452| --- | --- | --- | --- |
453| [`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` |
454| [`get`](/reference/api/actions/get-workflow/) | One workflow by its id, file name, path or name, as `list` gives it, with `source`, its file on `ref` (the default branch unless given). | `repo`, `workflow` | `workflows:read` |
455| [`list_runs`](/reference/api/actions/list-runs-of-workflow/) | Runs, newest first; filter by `workflow`, `branch`, `event`, `pull`, `sha`, or `status`: a status (`queued`, `in_progress`, `completed`) or a conclusion (`failure` for the failed runs, `success`, `cancelled`); `since` and `until` (RFC 3339) bound when they were created. | `repo` | `workflows:read` |
456| [`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` |
457| [`job_logs`](/reference/api/actions/get-job-logs/) | A job's log after `after`, or with `tail` its last chunks (at most 500), where a failed job says why; `done` says if more will come. | `repo`, `job` | `workflows:read` |
458| [`dispatch`](/reference/api/actions/dispatch-workflow/) | Run a `workflow_dispatch` workflow on `ref` with `inputs`. Write role. | `repo`, `workflow` | `workflows:write` |
459| [`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` |
460| [`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` |
461| [`update`](/reference/api/actions/update-workflow/) | Turn a workflow on or off. Maintain role. | `repo`, `workflow`, `enabled` | `workflows:write` |
462| [`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` |
463| [`run_artifacts`](/reference/api/actions/list-workflow-run-artifacts/) | One run's artifacts; `name`. | `repo`, `id` (the run) | `workflows:read` |
464| [`get_artifact`](/reference/api/actions/get-artifact/) | One artifact by its number. | `repo`, `id` | `workflows:read` |
465| [`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` |
466| [`delete_artifact`](/reference/api/actions/delete-artifact/) | Delete it before it expires. Write role. | `repo`, `id` | `workflows:write` |
467| [`artifact_retention`](/reference/api/actions/get-artifact-retention/) | The days the repository keeps artifacts, and the most it may. | `repo` | `workflows:read` |
468| [`set_artifact_retention`](/reference/api/actions/set-artifact-retention/) | Set those days, 1 to 90. Maintain role. | `repo`, `days` | `workflows:write` |
469| [`list_caches`](/reference/api/actions/list-caches/) | The repository's `actions/cache` entries: id, key, ref, size, when saved and last restored; `key` (a prefix), `ref`, `sort` (`last_accessed_at`, `created_at`, `size_in_bytes`), `direction`, `page`, `per_page`. | `repo` | `workflows:read` |
470| [`cache_usage`](/reference/api/actions/get-cache-usage/) | What the entries hold together, their count, and the repository's 10 GiB (`quota_bytes`). | `repo` | `workflows:read` |
471| [`delete_caches`](/reference/api/actions/delete-caches-by-key/) | Delete the entries whose key is exactly `key`; only `ref`'s with `ref`. Write role. | `repo`, `key` | `workflows:write` |
472| [`delete_cache`](/reference/api/actions/delete-cache/) | Delete one entry by its id. Write role. | `repo`, `id` | `workflows:write` |
473| [`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` |
474| [`list_statuses`](/reference/api/checks/list-commit-statuses/) | A commit's statuses, newest first. | `repo`, `ref` | `checks:read` |
475| [`set_status`](/reference/api/checks/create-commit-status/) | Set a status: `state`, `context`, `description`, `target_url`. Write role. | `repo`, `sha`, `state` | `checks:write` |
476| [`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` |
477| [`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` |
478| [`check_run_annotations`](/reference/api/checks/list-check-run-annotations/) | What a check run says about lines of files. | `repo`, `id` | `checks:read` |
479| [`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` |
480| [`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` |
481| [`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` |
482| [`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` |
483| [`get_check_suite`](/reference/api/checks/get-check-suite/) | One check suite: `cs_…`, or a workflow run's `run_…`. | `repo`, `id` | `checks:read` |
484| [`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` |
485| [`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` |
486| [`get_deployment`](/reference/api/deployments/get-deployment/) | One deployment with every status it has had, oldest first. | `repo`, `id` | `deployments:read` |
487| [`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` |
488| [`deployment_statuses`](/reference/api/deployments/list-deployment-statuses/) | A deployment's statuses, newest first. | `repo`, `id` | `deployments:read` |
489| [`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` |
490| [`list_environments`](/reference/api/deployments/list-environments/) | Environments with their address, current and latest deployments, production first. | `repo` | `deployments:read` |
491| [`get_environment`](/reference/api/deployments/get-environment/) | One environment by name, with its protection rules. | `repo`, `environment` | `deployments:read` |
492| [`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` |
493| [`get_deployment_settings`](/reference/api/deployments/get-deployment-settings/) | A project's g1t.page settings: `enabled`, `production`, `previews`, `production_url`, `primary_domain`, `build_as`, `build_command`, `output_dir`, `dockerfile`, `instance_type`, `idle_days`, `via_workflow`, and what its last build `detected`. A repository's own project has its name. Read role. | `workspace`, `project` | `deployments:read` |
494| [`update_deployment_settings`](/reference/api/deployments/update-deployment-settings/) | Change them; only what you give changes. `enabled: true` [turns deployments on](/guides/deployments/#turn-on-deployments) (production builds at once; refused without the g1t plan), `false` takes every app down. Admin role. | `workspace`, `project` | `repo:admin` |
495| [`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` |
496| [`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` |
497| [`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` |
498| [`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` |
499| [`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` |
500| [`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` |
501| [`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` |
502| [`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` |
503| [`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` |
504| [`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` |
505| [`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` |
506| [`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` |
507| [`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` |
508| [`get_approval_policy`](/reference/api/run-protection/get-fork-pr-approval/) | Which pull requests' runs wait for approval. | `repo` | `repo:read` |
509| [`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` |
510| [`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` |
511| [`set_access`](/reference/api/run-protection/set-actions-access/) | Set `access_level`: `none` or `organization`. Admin role. | `repo`, `access_level` | `repo:admin` |
512| [`get_enabled`](/reference/api/run-protection/get-actions-permissions/) | Whether its workflows run at all: `enabled` (on for a repository, off for a fork until someone chooses), `enabled_chosen`. | `repo` | `repo:read` |
513| [`set_enabled`](/reference/api/run-protection/set-actions-permissions/) | Turn its workflows on or off with `enabled`. Off, nothing starts a run. Admin role. | `repo`, `enabled` | `repo:admin` |
514| [`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` |
515| [`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` |
516| [`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` |
517| [`remove_runner`](/reference/api/runners/remove-runner-for-workspace/) | Remove a runner; a job it is running fails. | `workspace` or `repo`, `id` | `runners:admin` |
518| [`list_runner_groups`](/reference/api/runners/list-runner-groups/) | A workspace's runner groups and the repositories each serves. | `workspace` | `runners:read` |
519| [`create_runner_group`](/reference/api/runners/create-runner-group/) | A group for some `repositories` (empty for all). Owners. | `workspace`, `name` | `runners:admin` |
520| [`update_runner_group`](/reference/api/runners/update-runner-group/) | Rename a group or change its repositories. Owners. | `workspace`, `id` | `runners:admin` |
521| [`delete_runner_group`](/reference/api/runners/delete-runner-group/) | Delete a group; its runners join the default. Owners. | `workspace`, `id` | `runners:admin` |
522| [`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` |
523| [`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` |
524
525## `observability`
526
527What a project's running software did in production, to debug it: its
528requests, logs, traces, grouped errors and metrics, from its apps on
529g1t.page and from OpenTelemetry sent from anywhere. Name the project with
530`workspace` and `project` (its slug). `from` and `to` are RFC 3339 times or
531Unix milliseconds, the last 24 hours unless you say; `environment` and
532`service` narrow any list. Reading needs a role of your own on the
533project's repository, even when it is public. A project's settings, ingest
534tokens, exports and usage are in the [REST API](/reference/api/observability/get-observability-settings/)
535only. See [Observability](/guides/observability/).
536
537| Action | What it does | Required | Scope |
538| --- | --- | --- | --- |
539| [`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` |
540| [`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` |
541| [`request`](/reference/api/observability/get-request/) | One request with every log line it wrote. | `workspace`, `project`, `id` | `observability:read` |
542| [`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` |
543| [`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` |
544| [`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` |
545| [`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` |
546| [`update_error`](/reference/api/observability/update-error/) | Resolve, ignore or reopen an error group (`state`), or link the work item made for it (`item_number`, its number in the workspace; null to unlink). Triage role. | `workspace`, `project`, `fingerprint` | `observability:write` |
547| [`metrics`](/reference/api/observability/list-metrics/) | The metrics the project's software sends, with their kind, unit and services. | `workspace`, `project` | `observability:read` |
548| [`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` |
549
550## `package`
551
552A workspace's [packages](/guides/packages/) in every registry: their
553versions and downloads, deleting and restoring them within 30 days, their
554visibility and repository, the people and teams with a role on them, and
555which repositories' workflows may use them. Every action takes
556`workspace`; all but `list` also take `package_type` (`container`, `npm`,
557`cargo`, `maven`, `nuget`, `rubygems` or `composer`) and `package_name`.
558Reading access and every change also need the Admin role on the package.
559
560| Action | What it does | Required | Scope |
561| --- | --- | --- | --- |
562| [`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` |
563| [`get`](/reference/api/packages/get-package/) | One package: address, visibility, repository, versions, downloads. | `package_type`, `package_name` | `packages:read` |
564| [`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` |
565| [`get_version`](/reference/api/packages/get-package-version/) | One version by id, version, digest or tag. | `version_id` | `packages:read` |
566| [`update`](/reference/api/packages/update-package/) | Set `visibility` (unlinked packages), or `inherit_access` (linked ones). | `package_type`, `package_name` | `packages:write` |
567| [`link`](/reference/api/packages/link-package/) | Link it to a `repository` of its workspace; Admin on the repository too. | `repository` | `packages:write` |
568| [`unlink`](/reference/api/packages/unlink-package/) | Unlink it: the workspace's, private. | `package_type`, `package_name` | `packages:write` |
569| [`access`](/reference/api/packages/list-package-access/) | People and teams with a role on it, and `inherit_access`. | `package_type`, `package_name` | `packages:read` |
570| [`set_access`](/reference/api/packages/set-package-access/) | Give `username` or `team` a `role`: `read`, `write` or `admin`. | `role` | `packages:write` |
571| [`remove_access`](/reference/api/packages/remove-package-access/) | Take `username`'s or `team`'s role away. | `package_type`, `package_name` | `packages:write` |
572| [`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` |
573| [`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` |
574| [`remove_actions_access`](/reference/api/packages/remove-package-actions-access/) | Stop a `repository`'s workflows using it. | `repository` | `packages:write` |
575| [`delete`](/reference/api/packages/delete-package/) | Delete it, restorable for 30 days; its name stays taken until then. | `package_type`, `package_name` | `packages:delete` |
576| [`restore`](/reference/api/packages/restore-package/) | Restore a deleted package. | `package_type`, `package_name` | `packages:delete` |
577| [`delete_version`](/reference/api/packages/delete-package-version/) | Delete a version, restorable for 30 days. | `version_id` | `packages:delete` |
578| [`restore_version`](/reference/api/packages/restore-package-version/) | Restore a deleted version. | `version_id` | `packages:delete` |
579
580## `secret`
581
582A repository's or a workspace's secrets and variables, which workflows and
583deployments read. Give `repo` for a repository's, or `workspace` for a
584workspace's own. Secret values are never returned.
585
586| Action | What it does | Required | Scope |
587| --- | --- | --- | --- |
588| [`list_secrets`](/reference/api/secrets-and-variables/list-actions-secrets/) | Secrets' rows: key, environments, who reads them. Never values. | None | `secrets:read` |
589| [`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` |
590| [`delete_secret`](/reference/api/secrets-and-variables/delete-actions-secret/) | Remove one row (`id`) or every row of the key. | `setting` | `secrets:admin` |
591| [`list_variables`](/reference/api/secrets-and-variables/list-actions-variables/) | Config rows with their values. | None | `secrets:read` |
592| [`set_variable`](/reference/api/secrets-and-variables/set-actions-variable/) | Add or change a config row, as for secrets. | `setting` | `secrets:admin` |
593| [`delete_variable`](/reference/api/secrets-and-variables/delete-actions-variable/) | Remove one row (`id`) or every row of the key. | `setting` | `secrets:admin` |
594
595## `security`
596
597A repository's [security](/guides/security/): secret scanning alerts and
598push protection bypasses, [custom patterns](/guides/security/secret-protection/#custom-patterns),
599[code scanning](/guides/security/code-scanning/) and SARIF uploads,
600vulnerability alerts, the [dependency graph and its SBOM](/guides/security/supply-chain/),
601dependency review, settings, and a workspace's
602[overview](/guides/security/security-overview/). `secret_alerts` is the
603default action. Findings are shown only to those with Write on the
604repository, and to the workspace's security managers; on private repositories, some actions need the
605g1t plan, as [Security and quality](/guides/security/pricing/), and are
606refused with `402` without it.
607
608| Action | What it does | Required | Scope |
609| --- | --- | --- | --- |
610| [`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` |
611| [`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` |
612| [`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` |
613| [`secret_locations`](/reference/api/secret-scanning/list-secret-scanning-locations/) | Every file, line and commit a secret is in. | `repo`, `id` | `security:read` |
614| [`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` |
615| [`check_validity`](/reference/api/secret-scanning/check-secret-validity/) | Ask a landed secret's issuer whether it still works. | `repo`, `id` | `security:write` |
616| [`bypass_requests`](/reference/api/secret-scanning/list-bypass-requests/) | A workspace's bypass requests, pending first; filter with `state` and `repo`. | `workspace` | `security:read` |
617| [`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` |
618| [`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` |
619| [`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` |
620| [`update_pattern`](/reference/api/secret-scanning/update-custom-pattern/) | Change, publish or unpublish one. | `id`, `pattern_name`, `pattern` | `security:write` |
621| [`delete_pattern`](/reference/api/secret-scanning/delete-custom-pattern/) | Delete one; its alerts stay. | `id` | `security:write` |
622| [`dry_run_pattern`](/reference/api/secret-scanning/dry-run-custom-pattern/) | Run a `pattern` over the default branch without saving it. | `pattern` | `security:write` |
623| [`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` |
624| [`code_alert`](/reference/api/code-scanning/get-code-scanning-alert/) | One alert by `number`, with its activity and analyses. | `repo`, `number` | `security:read` |
625| [`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` |
626| [`analyses`](/reference/api/code-scanning/list-code-scanning-analyses/) | Analyses, newest first. | `repo` | `security:read` |
627| [`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` |
628| [`sarif_upload`](/reference/api/code-scanning/get-sarif-upload/) | Whether an upload was read, its analyses and errors. | `repo`, `id` | `security:read` |
629| [`vulnerability_alerts`](/reference/api/supply-chain/list-vulnerability-alerts/) | Vulnerability alerts: `repo`, or `workspace`. Filter with `state`, `severity`, `ecosystem`, `package`. | None | `security:read` |
630| [`vulnerability_alert`](/reference/api/supply-chain/get-vulnerability-alert/) | One alert by `id`. | `repo`, `id` | `security:read` |
631| [`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` |
632| [`dependency_graph`](/reference/api/supply-chain/get-dependency-graph/) | Every package the lockfiles resolve, direct or transitive, with licenses. | `repo` | `security:read` |
633| [`sbom`](/reference/api/supply-chain/get-sbom/) | The dependency graph as an SPDX 2.3 document, in `sbom`. | `repo` | `security:read` |
634| [`compare_dependencies`](/reference/api/supply-chain/compare-dependencies/) | What changes between `basehead` (`base...head`), and whether it passes dependency review. | `repo`, `basehead` | `security:read` |
635| [`rerun_dependency_review`](/reference/api/supply-chain/rerun-dependency-review/) | Runs a pull request's Dependency review check again; its one comment changes in place. Write role. | `repo`, `number` | `security:write` |
636| [`settings`](/reference/api/security-settings/get-security-settings/) | A repository's security settings, and whether the paid features are on. | `repo` | `security:read` |
637| [`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` |
638| [`workspace_settings`](/reference/api/security-settings/get-workspace-security-settings/) | A workspace's delegated bypass and validity checks. | `workspace` | `security:read` |
639| [`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` |
640| [`overview`](/reference/api/security-settings/get-security-overview/) | A workspace's alerts by type and severity, trends and coverage. | `workspace` | `security:read` |
641
642## `webhook`
643
644HTTPS addresses that are sent signed events as they happen. Give `repo` for
645a repository's webhooks, or `workspace` for a workspace's own. See
646[webhooks](/guides/webhooks/).
647
648| Action | What it does | Required | Scope |
649| --- | --- | --- | --- |
650| [`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` |
651| [`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` |
652| [`update`](/reference/api/webhooks/update-webhook/) | Change its `url`, `events`, or whether it is `active`. | `id` | `webhooks:admin` |
653| [`delete`](/reference/api/webhooks/delete-webhook/) | Remove it and its delivery log. | `id` | `webhooks:admin` |
654| [`ping`](/reference/api/webhooks/ping-webhook/) | Send it a ping. | `id` | `webhooks:admin` |
655| [`list_deliveries`](/reference/api/webhooks/list-webhook-deliveries/) | Its latest deliveries, with request, response and retries. | `id` | `webhooks:read` |
656| [`redeliver`](/reference/api/webhooks/redeliver-webhook/) | Send a delivery again. | `delivery` | `webhooks:admin` |
657
658## `access`
659
660Who can do what in a repository: its people and their
661[roles](/guides/access-and-roles/) (read, triage, write, maintain and
662admin), invitations, outside collaborators, a workspace's base
663permission, and a repository's [deploy keys](/guides/git/#deploy-keys).
664
665| Action | What it does | Required | Scope |
666| --- | --- | --- | --- |
667| [`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` |
668| [`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` |
669| [`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` |
670| [`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` |
671| [`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` |
672| [`list_invitations`](/reference/api/access/list-repo-invitations/) | Its pending invitations. Needs the Admin role. | `repo` | `access:read` |
673| [`revoke_invitation`](/reference/api/access/revoke-repo-invitation/) | Withdraw a pending invitation. Needs the Admin role. | `repo`, `id` | `access:admin` |
674| [`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` |
675| [`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` |
676| [`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` |
677| [`get_deploy_key`](/reference/api/access/get-deploy-key/) | One deploy key. Needs the Admin role. | `repo`, `id` | `access:read` |
678| [`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` |
679| [`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` |
680
681## `team`
682
683[Teams](/guides/teams/): groups of a workspace's members, given roles on
684repositories together, mentioned as `@workspace/team` and asked to review
685together. Name a team by `workspace` and its slug, `team`. Any member may
686create one; the workspace's owners and the team's maintainers manage it. A
687`secret` team is seen only by its own people and the owners. Changes are
688for people: a workspace's token cannot make them.
689
690| Action | What it does | Required | Scope |
691| --- | --- | --- | --- |
692| [`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` |
693| [`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` |
694| [`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` |
695| [`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` |
696| [`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` |
697| [`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` |
698| [`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` |
699| [`remove_member`](/reference/api/teams/remove-team-member/) | Take someone out. Owners and its maintainers; anyone may leave. | `workspace`, `team`, `username` | `workspace:admin` |
700| [`list_child_teams`](/reference/api/teams/list-child-teams/) | The teams nested directly under it. | `workspace`, `team` | `workspace:read` |
701| [`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` |
702| [`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` |
703| [`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` |
704| [`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` |
705| [`list_user_teams`](/reference/api/teams/list-user-teams/) | The teams someone is in. Members only. | `workspace`, `username` | `workspace:read` |
706
707## `workspace`
708
709Workspaces own repositories: read what happened across them (`activity`:
710what merged, shipped and deployed, by whom), create, update or delete one,
711invite members,
712manage its members and owners,
713connect [integrations](/guides/integrations/), manage the
714[labels](/work/labels/) and [milestones](/work/milestones/) its work
715items and pull requests share, read and
716change its [projects](/guides/projects/) (what each is, where it runs, its
717links), and keep your own
718[pinned projects](/guides/workspaces/#pinned-and-recent-projects) at the top
719of its sidebar. See [workspaces](/guides/workspaces/).
720
721| Action | What it does | Required | Scope |
722| --- | --- | --- | --- |
723| [`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` |
724| [`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` |
725| [`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` |
726| [`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` |
727| [`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` |
728| [`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` |
729| [`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` |
730| [`leave`](/reference/api/members/leave-workspace/) | Leave it yourself. Never the last owner. | `workspace` | `account:write` |
731| [`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` |
732| [`list_invites`](/reference/api/invites/list-workspace-invites/) | A workspace's invites. Owners only. | `workspace` | `workspace:read` |
733| [`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` |
734| [`revoke_invite`](/reference/api/invites/revoke-workspace-invite/) | Revoke a workspace's pending invite. Owners only. | `workspace`, `id` | `workspace:admin` |
735| [`list_integrations`](/reference/api/integrations/list-integrations/) | The workspace's alert sources and trackers. Secrets are never returned. Members only. | `workspace` | `workspace:read` |
736| [`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` |
737| [`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` |
738| [`disconnect_integration`](/reference/api/integrations/disconnect-integration/) | Remove it and its secrets. Owners only. | `workspace`, `id` | `workspace:admin` |
739| [`test_integration`](/reference/api/integrations/test-integration/) | Check its credentials against the system it connects to. Owners only. | `workspace`, `id` | `workspace:admin` |
740| [`activity`](/reference/api/workspaces/get-workspace-activity/) | What happened across its repositories you can read, newest first: pull requests merged, opened and closed, work items, releases, deployments, pushes (`default_branch` marks what landed without a pull request), reviews and packages, each with its `repo`, `actor`, `number`, `title` and `url` where it has them, and a `summary` of what shipped. `landed` lists the commits that reached default branches, with each author's `username` when known and `production` (`live`, `deploying`, `failed` or `not_deployed`, with the `deploy` that decided it) where the repository deploys: a project's production deployment, or a successful run of its deploy workflow on the default branch. `since` and `until` (RFC 3339; the last 24 hours by default, at most 31 days), `kinds` (`merged`, `pulls`, `work_items`, `releases`, `deployments`, `pushes`, `reviews`, `comments`, `packages`, `runs`; all but `comments` when left out) and `limit` (at most 200) narrow it; `complete` is false when more happened than was read. | `workspace` | `repo:read` |
741| [`list_labels`](/reference/api/labels-and-milestones/list-labels/) | Its labels by name, each with `color`, `description`, and how many work items (`items`) and pull requests (`pulls`) carry it. | `workspace` | `work:read` |
742| [`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 in the workspace. | `workspace`, `label` | `work:write` |
743| [`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 in the workspace. | `workspace`, `label` | `work:write` |
744| [`delete_label`](/reference/api/labels-and-milestones/delete-label/) | Delete a label, from everything that carries it. Write role in the workspace. | `workspace`, `label` | `work:write` |
745| [`add_default_labels`](/reference/api/labels-and-milestones/add-default-labels/) | Add the default labels it is missing. Write role in the workspace. | `workspace` | `work:write` |
746| [`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. | `workspace` | `work:read` |
747| [`get_milestone`](/reference/api/labels-and-milestones/get-milestone/) | One milestone with its work items and pull requests. | `workspace`, `milestone` | `work:read` |
748| [`create_milestone`](/reference/api/labels-and-milestones/create-milestone/) | Create a milestone with `title`, `description` and `due_on` (`YYYY-MM-DD`). Write role in the workspace. | `workspace`, `title` | `work:write` |
749| [`update_milestone`](/reference/api/labels-and-milestones/update-milestone/) | Change its `title`, `description`, `due_on` (`""` clears it) or `state` (`open` or `closed`). Write role in the workspace. | `workspace`, `milestone` | `work:write` |
750| [`delete_milestone`](/reference/api/labels-and-milestones/delete-milestone/) | Delete a milestone; what was in it is in none. Write role in the workspace. | `workspace`, `milestone` | `work:write` |
751| [`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` |
752| [`get_project`](/reference/api/projects/get-project/) | One project, with what a person set (`setting`) and what detection decides (`detected`). | `workspace`, `project` | `repo:read` |
753| [`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 (the homepage goes back to the repository's website), and `links` replaces its other links (at most 10). Maintain role or higher. | `workspace`, `project` | `repo:write` |
754| [`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` |
755| [`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` |
756| [`unpin_project`](/reference/api/pinned-projects/unpin-project/) | Unpin it. Returns your pins. | `workspace`, `project` | `account:write` |
757| [`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` |
758| [`list_rulesets`](/reference/api/rules/list-workspace-rulesets/) | The workspace's own [rulesets](/guides/rules/). Members only. | `workspace` | `workspace:read` |
759| [`get_ruleset`](/reference/api/rules/get-workspace-ruleset/) | One of them by `id`. Members only. | `workspace`, `id` | `workspace:read` |
760| [`create_ruleset`](/reference/api/rules/create-workspace-ruleset/) | Create one, with `conditions.repository` choosing its repositories. Owners only. | `workspace` | `workspace:admin` |
761| [`update_ruleset`](/reference/api/rules/update-workspace-ruleset/) | Change one. Owners only. | `workspace`, `id` | `workspace:admin` |
762| [`delete_ruleset`](/reference/api/rules/delete-workspace-ruleset/) | Delete one. Owners only. | `workspace`, `id` | `workspace:admin` |
763| [`rule_evaluations`](/reference/api/rules/list-workspace-rule-evaluations/) | How rules judged changes across its repositories, with insights. Members only. | `workspace` | `workspace:read` |
764| [`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` |
765| [`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` |
766| [`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` |
767| [`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` |
768| [`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` |
769| [`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` |
770
771## `ai`
772
773A workspace's AI: the [AI providers](/guides/ai/) it keeps keys for
774(frontier labs, model platforms and self-hosted endpoints) and what
775[Ask g1t](/guides/ask/) answers with. `list_providers` is the default
776action. Keys are sealed and never returned. g1t hosts no model and bills
777nothing for it: it runs on the workspace's own account. Members read it;
778changing it is for owners.
779
780| Action | What it does | Required | Scope |
781| --- | --- | --- | --- |
782| [`list_providers`](/reference/api/ai/list-ai-providers/) | Its AI providers, each with its `group` (`labs`, `platforms` or `self_hosted`), `config`, `secret_hint`, the `models` it offered when last checked and its `last_error`. Members only. | `workspace` | `workspace:read` |
783| [`add_provider`](/reference/api/ai/add-ai-provider/) | Add one: `provider` (such as `anthropic`, `openai`, `openrouter`, `azure_openai`, `anthropic_endpoint` or `openai_endpoint`), `config` (`base_url`, `auth_header`, `model`) and `secret`, its key, checked as it is saved. Owners only. | `workspace`, `provider` | `workspace:admin` |
784| [`update_provider`](/reference/api/ai/update-ai-provider/) | Change one: its `name`, its `config` (replaced whole) or its `secret` (write-only, never returned). Owners only. | `workspace`, `id` | `workspace:admin` |
785| [`remove_provider`](/reference/api/ai/remove-ai-provider/) | Remove it and its key. Owners only. | `workspace`, `id` | `workspace:admin` |
786| [`test_provider`](/reference/api/ai/test-ai-provider/) | Check its key against the provider. Owners only. | `workspace`, `id` | `workspace:admin` |
787| [`get_ask`](/reference/api/ai/get-ask-settings/) | What Ask answers with: `provider_id`, `provider_name`, `provider`, `model`, `auto`, and `problem` when it cannot answer. Members only. | `workspace` | `workspace:read` |
788| [`set_ask`](/reference/api/ai/set-ask-settings/) | Choose `provider_id` and `model` (one the provider offers, or `auto`); no `provider_id` turns Ask off. Owners only. | `workspace` | `workspace:admin` |
789
790## `billing`
791
792A workspace's billing: its usage, its budget and its invoices. `usage` is
793the default action. Amounts are whole millionths of a dollar (`_micros`),
794or cents where a field says `_cents`. Members of the workspace read it, a
795workspace's own token included. Changing the budget is for its owners, as
796people: signed in or with a personal access token. A workspace's token
797never changes billing, whatever its scopes, and no preset but full access
798includes `billing:write`. See [usage and billing](/guides/usage-and-billing/).
799
800| Action | What it does | Required | Scope |
801| --- | --- | --- | --- |
802| [`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` |
803| [`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` |
804| [`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` |
805| [`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` |
806| [`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` |
807
808## `notifications`
809
810Your [notifications](/guides/notifications/): one thread per work item, pull request, workflow
811on a branch or deployment, with why you were told (`reason`), and what you
812subscribe to and watch. `list` is the default action. It is your own: a
813personal access token or an OAuth sign-in can use it, a workspace's token
814cannot. Name a work item by a thread's `id`, or by `workspace` and
815`number`; a pull request by a thread's `id`, or by `repo` and `number`.
816
817| Action | What it does | Required | Scope |
818| --- | --- | --- | --- |
819| [`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` |
820| [`get`](/reference/api/notifications/get-notification-thread/) | One thread, its last 10 activities, and your subscription to it. | `id` | `notifications:read` |
821| [`mark_read`](/reference/api/notifications/mark-thread-read/) | Mark a thread read, or with `read` false, unread. | `id` | `notifications:write` |
822| [`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` |
823| [`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` |
824| [`save`](/reference/api/notifications/save-thread/) | Save a thread so it is kept, or with `saved` false, unsave it. | `id` | `notifications:write` |
825| [`snooze`](/reference/api/notifications/snooze-thread/) | Hide a thread until `until` (RFC 3339). Leave `until` out to bring it back now. | `id` | `notifications:write` |
826| [`subscription`](/reference/api/notifications/get-thread-subscription/) | Whether you are subscribed to a work item or pull request, or ignore it, and why. | `id`, or `workspace` or `repo`, and `number` | `notifications:read` |
827| [`subscribe`](/reference/api/notifications/set-thread-subscription/) | Subscribe (`subscribed`, true unless you say), unsubscribe (`subscribed` false), or ignore it (`ignored` true). | `id`, or `workspace` or `repo`, and `number` | `notifications:write` |
828| [`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 `workspace` or `repo`, and `number` | `notifications:write` |
829| [`watching`](/reference/api/notifications/get-repo-subscription/) | How you watch a repository: `participating`, `all`, `ignore` or `custom`, with `events`. | `repo` | `notifications:read` |
830| [`watch`](/reference/api/notifications/set-repo-subscription/) | Watch a repository at a `level`, with `events` (`work_items`, `pulls`, `deployments`, `security`) for `custom`: `work_items` is the work items linked to it. | `repo` | `notifications:write` |
831| [`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` |
832| [`watched`](/reference/api/notifications/list-watched-repos/) | The repositories you watch other than the default way. | None | `notifications:read` |
833
834## `account`
835
836Who the token acts as and its workspaces, your email addresses, your
837[invites to g1t](/guides/authentication/#invite-a-friend), and
838[invitations](/guides/authentication/#invites) to workspaces and
839repositories waiting for you. `whoami` is the default
840action, and needs no scope. A workspace's token cannot
841use the email, invite and invitation actions. An account that has not confirmed its
842email address gets `403` from every tool until it does; see
843[until you confirm](/guides/authentication/#until-you-confirm).
844
845| Action | What it does | Required | Scope |
846| --- | --- | --- | --- |
847| [`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 |
848| [`list_emails`](/reference/api/accounts/list-emails/) | Your email addresses and email settings. People only. | None | `account:read` |
849| [`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` |
850| [`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` |
851| [`remove_email`](/reference/api/accounts/remove-email/) | Remove an address; never the primary or the last confirmed one. | `email`, `password` | `account:write` |
852| [`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` |
853| [`list_invites`](/reference/api/invites/list-invites/) | Your invites to g1t, with who joined, and how many of your 20 are left. | None | `account:read` |
854| [`create_invite`](/reference/api/invites/create-invite/) | Invite a friend to g1t by email, with an optional `message`. With `workspace` (one you own on a paid plan) and `role`, also invite them to it. Uses one of your invites; refused with `409` when the address has an account or you already have a pending invite for it. | `email` | `account:write` |
855| [`revoke_invite`](/reference/api/invites/revoke-invite/) | Revoke a pending invite to g1t; it comes back to you. | `id` | `account:write` |
856| [`resend_invite`](/reference/api/invites/resend-invite/) | Send a pending invite to g1t again. | `id` | `account:write` |
857| [`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` |
858| [`accept_workspace_invitation`](/reference/api/invites/accept-invitation/) | Accept one; you join the workspace at once with its role. | `id` | `account:write` |
859| [`decline_workspace_invitation`](/reference/api/invites/decline-invitation/) | Decline one; whoever sent it is told. | `id` | `account:write` |
860| [`list_repository_invitations`](/reference/api/access/list-my-repo-invitations/) | The invitations to repositories waiting for your answer. | None | `account:read` |
861| [`accept_repository_invitation`](/reference/api/access/accept-repo-invitation/) | Accept one; its role is yours at once. | `id` | `account:write` |
862| [`decline_repository_invitation`](/reference/api/access/decline-repo-invitation/) | Decline one. | `id` | `account:write` |
863
864## `artifact`
865
866A workspace's artifacts: its docs, and later its slides, designs and
867dashboards. Each action runs as you: it finds and opens only what you can
868open, and changes only what your role on it allows, whatever the token's
869scope. Name one by its id (`fol_…`) or its link as `artifact_id`, and its
870space by slug or id. Not workflow runs' artifacts, which are the
871`workflow` tool's. Slides, designs and dashboards answer `422` saying they
872are not here yet. A workspace's own token cannot use this tool. See
873[artifacts](/guides/bring-your-own-agent/#artifacts).
874
875| Action | What it does | Required | Scope |
876| --- | --- | --- | --- |
877| [`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` |
878| [`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` |
879| [`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` |
880| [`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` |
881| [`versions`](/reference/api/artifacts/list-workspace-artifact-versions/) | Its saved versions, newest first, with who made each. | `workspace`, `artifact_id` | `artifacts:read` |
882| [`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` |
883| [`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` |
884| [`spaces`](/reference/api/artifacts/list-workspace-artifact-spaces/) | The spaces in your Artifacts sidebar, with your role in each. | `workspace` | `artifacts:read` |
885| [`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` |
886| [`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` |
887| [`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` |
888| [`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` |
889| [`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` |
890| [`restore`](/reference/api/artifacts/restore-workspace-artifact/) | Bring it back from the trash. | `workspace`, `artifact_id` | `artifacts:write` |
891| [`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` |
892| [`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` |
893| [`purge`](/reference/api/artifacts/purge-workspace-artifact/) | Delete one in the trash for good. Takes full access to it. | `workspace`, `artifact_id` | `artifacts:admin` |