| 1 | --- |
| 2 | title: API reference |
| 3 | description: The REST API at api.g1t.sh, its authentication, errors and conventions, and a page for every endpoint. |
| 4 | --- |
| 5 | |
| 6 | The REST API lives at `https://api.g1t.sh`. It exposes the same operations |
| 7 | as the [MCP server](/reference/mcp/): every endpoint names the MCP tool and |
| 8 | action that do the same thing, with the same inputs. |
| 9 | |
| 10 | This page covers what every endpoint shares. The pages under each resource |
| 11 | in the sidebar document one endpoint each: its parameters, an example |
| 12 | request and response, and its errors. The machine-readable description is |
| 13 | at [api.g1t.sh/openapi.json](https://api.g1t.sh/openapi.json), and the |
| 14 | [explorer](/api/reference/) lets you call the API from the browser. |
| 15 | |
| 16 | ## Start at the root |
| 17 | |
| 18 | The API is public. Anything you could see on the site without signing in, |
| 19 | you can read without a token. `GET https://api.g1t.sh/` returns where |
| 20 | everything is, as URL templates: |
| 21 | |
| 22 | ```sh |
| 23 | curl https://api.g1t.sh/ |
| 24 | ``` |
| 25 | |
| 26 | ```json |
| 27 | { |
| 28 | "documentation_url": "https://docs.g1t.sh/reference/api/", |
| 29 | "openapi_url": "https://api.g1t.sh/openapi.json", |
| 30 | "mcp_url": "https://mcp.g1t.sh", |
| 31 | "current_user_url": "https://api.g1t.sh/user", |
| 32 | "repository_url": "https://api.g1t.sh/repos/{owner}/{name}", |
| 33 | "issues_url": "https://api.g1t.sh/repos/{owner}/{name}/issues{?state,label}", |
| 34 | "pulls_url": "https://api.g1t.sh/repos/{owner}/{name}/pulls{?state}" |
| 35 | } |
| 36 | ``` |
| 37 | |
| 38 | The response has more entries than shown here. |
| 39 | |
| 40 | ## Authentication |
| 41 | |
| 42 | A token is needed to change anything, and to see what is private. Send an |
| 43 | [access token](https://g1t.sh/settings/tokens) as a bearer token: |
| 44 | |
| 45 | ```sh |
| 46 | curl https://api.g1t.sh/user \ |
| 47 | -H "Authorization: Bearer $G1T_TOKEN" |
| 48 | ``` |
| 49 | |
| 50 | `Authorization: token $G1T_TOKEN`, the other form GitHub takes, works the |
| 51 | same, so Octokit and the actions built on it, such as `actions/checkout` |
| 52 | and `actions/github-script`, are signed in with the token they are given. |
| 53 | |
| 54 | Public data can be read without a token. A token that is not valid is |
| 55 | rejected with `401` rather than treated as anonymous. Each endpoint's page |
| 56 | says whether it needs a token. |
| 57 | |
| 58 | A [workspace's own token](/guides/workspaces/#workspace-access-tokens) acts |
| 59 | as the workspace. The token g1t works with can use only the |
| 60 | operations its task needs, in its own repository. |
| 61 | |
| 62 | ### Scopes |
| 63 | |
| 64 | Each endpoint needs one [scope](/guides/authentication/#scopes), such as |
| 65 | `issues:read` to read an issue or `issues:write` to open one. Its page |
| 66 | says which, and the [OpenAPI document](https://api.g1t.sh/openapi.json) |
| 67 | gives it as `x-scope` on each operation, beside `x-mcp-tool` and |
| 68 | `x-mcp-action`, the MCP tool and action that do the same: |
| 69 | |
| 70 | ```json |
| 71 | { |
| 72 | "operationId": "get_issue", |
| 73 | "x-operation": "get_issue", |
| 74 | "x-mcp-tool": "issue", |
| 75 | "x-mcp-action": "get", |
| 76 | "x-scope": "issues:read" |
| 77 | } |
| 78 | ``` |
| 79 | |
| 80 | `x-scope` is `null` for `GET /user`, which any token may use. A token |
| 81 | needs the scope, and whoever it acts as needs a role that allows the call. |
| 82 | A token reaches every workspace and repository whoever it acts as can. |
| 83 | |
| 84 | ## Signing in from a tool |
| 85 | |
| 86 | A tool gets a token by having a person approve a short code in their |
| 87 | browser: [start signing in](/reference/api/accounts/device-code/), then |
| 88 | [finish signing in](/reference/api/accounts/device-token/). See |
| 89 | [signing in from a tool](/guides/authentication/#signing-in-from-a-tool). |
| 90 | |
| 91 | Applications that can open a browser use OAuth instead. See |
| 92 | [signing in with OAuth](/guides/authentication/#signing-in-with-oauth). |
| 93 | |
| 94 | | Method | Path | | |
| 95 | | --- | --- | --- | |
| 96 | | `GET` | `/.well-known/oauth-authorization-server` | Where the endpoints are. | |
| 97 | | `POST` | `/oauth/register` | Register a client. Body: `client_name`, `redirect_uris`. | |
| 98 | | `POST` | `/oauth/token` | Exchange a code, or refresh. Form-encoded or JSON. | |
| 99 | |
| 100 | Accounts are created in a browser only. There is no registration endpoint |
| 101 | for accounts. |
| 102 | |
| 103 | ## Requests and responses |
| 104 | |
| 105 | Request bodies are JSON. |
| 106 | |
| 107 | Every name in a body is `snake_case`, both ways: responses, errors, MCP |
| 108 | results and [webhook](/guides/webhooks/) payloads. Request bodies take the |
| 109 | same names as the MCP tools, and also accept the `camelCase` spelling: |
| 110 | |
| 111 | ```sh |
| 112 | # Both require pull requests to be up to date before they merge. |
| 113 | curl -X PATCH https://api.g1t.sh/repos/flagon-io/hello/settings \ |
| 114 | -H "Authorization: Bearer $G1T_TOKEN" -d '{"require_up_to_date": true}' |
| 115 | curl -X PATCH https://api.g1t.sh/repos/flagon-io/hello/settings \ |
| 116 | -H "Authorization: Bearer $G1T_TOKEN" -d '{"requireUpToDate": true}' |
| 117 | ``` |
| 118 | |
| 119 | When a body gives a field both ways, the `snake_case` one is used. |
| 120 | |
| 121 | Names you chose are never changed: a workflow's `inputs`, the names of |
| 122 | secrets and variables, an environment's `env`, a job's `outputs` and |
| 123 | `matrix`, labels and headers come back exactly as they were written. |
| 124 | |
| 125 | Every person in a response, such as an issue's `author`, a workspace's |
| 126 | members or whoever `whoami` is, has two usernames: |
| 127 | |
| 128 | - `username` is lowercased. It is what an account is found, linked and |
| 129 | mentioned by, and it never changes case, so match on it. |
| 130 | - `display_username` is the username as its owner wrote it, such as |
| 131 | `Ana`. It is the same as `username` when they chose no case. Show it. |
| 132 | |
| 133 | ```json |
| 134 | { "id": "usr_01kkntcg1eeb98j62xjm7eh09p", "username": "ana", "display_username": "Ana" } |
| 135 | ``` |
| 136 | |
| 137 | Requests take a username in any case: `Ana` and `ana` are the same person. |
| 138 | |
| 139 | A successful request answers `200` with the result as the body: an object, |
| 140 | a list, or `true` for a deletion. There is no envelope around it. |
| 141 | |
| 142 | In paths, `{owner}` is the workspace that owns the repository and `{name}` |
| 143 | is the repository's name. Issues and pull requests are addressed by |
| 144 | `{number}`; the two share one sequence of numbers per repository, so a |
| 145 | number names exactly one of them. |
| 146 | |
| 147 | ## Errors |
| 148 | |
| 149 | Errors are JSON with a stable `code` and a human-readable `message`. |
| 150 | |
| 151 | ```json |
| 152 | { "error": { "code": "not_found", "message": "Repository not found." } } |
| 153 | ``` |
| 154 | |
| 155 | | Status | Code | Meaning | |
| 156 | | --- | --- | --- | |
| 157 | | 401 | `unauthenticated` | A token is required, or the one sent is not valid. | |
| 158 | | 402 | `payment_required` | The workspace's plan or limits do not allow this: for example, a free workspace inviting someone, or making a repository private, or moving a private one in, without room in its free private storage. See [usage and billing](/guides/usage-and-billing/#when-work-is-stopped). | |
| 159 | | 403 | `forbidden` | You are signed in but not allowed to do this: your role is not enough, or the token lacks a scope, which `needed_scope` names. | |
| 160 | | 404 | `not_found` | It does not exist, or you cannot see it. A path that is not an endpoint answers this too. | |
| 161 | | 409 | `conflict` | The request conflicts with the current state. | |
| 162 | | 422 | `invalid` | The input is not valid. | |
| 163 | | 429 | `rate_limited` | Too many requests in the last minute. Wait the seconds `Retry-After` says. See [rate limits](#rate-limits). | |
| 164 | |
| 165 | Branch on `code`, not on `message`: messages are written for people and |
| 166 | may change. |
| 167 | |
| 168 | When an access token lacks the scope a call needs, the `403` also names |
| 169 | that scope in `needed_scope`: |
| 170 | |
| 171 | ```json |
| 172 | { |
| 173 | "error": { |
| 174 | "code": "forbidden", |
| 175 | "message": "This access token needs the issues:write scope to use create_issue.", |
| 176 | "needed_scope": "issues:write" |
| 177 | } |
| 178 | } |
| 179 | ``` |
| 180 | |
| 181 | Give the token that permission on its page under |
| 182 | [Settings → Access tokens](https://g1t.sh/settings/tokens), or use another |
| 183 | token. A `403` for any other reason has no `needed_scope`. |
| 184 | |
| 185 | ## Rate limits |
| 186 | |
| 187 | Each token may make 1,000 requests a minute. Requests without a token are |
| 188 | limited to 60 a minute for each IP address. Past either, the API answers |
| 189 | `429` with `rate_limited` and a `Retry-After` header saying how many |
| 190 | seconds to wait: |
| 191 | |
| 192 | ```json |
| 193 | { "error": { "code": "rate_limited", "message": "Too many requests with this token. Wait a minute and try again: https://docs.g1t.sh/reference/rate-limits/" } } |
| 194 | ``` |
| 195 | |
| 196 | Every limit, and how to stay under them, is on [rate limits](/reference/rate-limits/). |
| 197 | |
| 198 | ## Lists |
| 199 | |
| 200 | Lists come newest first, unless an endpoint says otherwise. Most return |
| 201 | everything up to a limit; the few that grow without bound take a cursor: |
| 202 | |
| 203 | | Endpoint | Limit | Next page | |
| 204 | | --- | --- | --- | |
| 205 | | [List repositories](/reference/api/repositories/list-repos/) | 50 | None | |
| 206 | | [List issues](/reference/api/issues/list-issues/) | 100 | None | |
| 207 | | [List pull requests](/reference/api/pull-requests/list-pull-requests/) | 100 | None | |
| 208 | | [List repository events](/reference/api/repositories/list-events/) | 50 | `before`: the id of the last event you have | |
| 209 | | [List workflow runs](/reference/api/actions/list-workflow-runs/) | `per_page`, at most 100 and 50 if not given | None | |
| 210 | | [List webhook deliveries](/reference/api/webhooks/list-webhook-deliveries/) | 50 | None | |
| 211 | | [List notifications](/reference/api/notifications/list-notifications/) | `per_page`, at most 100 and 30 if not given | `cursor`: the `next` of the page before | |
| 212 | | [Read a session](/reference/api/sessions/read-session/) | None | `after`: the last `seq` you have | |
| 213 | | [Get a job's log](/reference/api/actions/get-job-logs/) | 500 chunks | `after`: the last `seq` you have | |
| 214 | |
| 215 | ## Identifiers and times |
| 216 | |
| 217 | Issues and pull requests are addressed by repository and number. Other ids |
| 218 | are [TypeIDs](https://github.com/jetify-com/typeid): a prefix naming the |
| 219 | kind of thing, then a UUIDv7 in base32, for example |
| 220 | `pr_01jb2k7x9hfq0b3zj0f5s2m8ra`. They sort by creation time. |
| 221 | |
| 222 | Times are RFC 3339 in UTC, with milliseconds, such as |
| 223 | `2026-10-01T18:04:11.482Z`. |
| 224 | |
| 225 | ## Resources |
| 226 | |
| 227 | | Resource | | |
| 228 | | --- | --- | |
| 229 | | [Accounts](/reference/api/accounts/whoami/) | Signing in from a tool, and who a token acts as. Accounts are made and [deleted](/guides/authentication/#deleting-your-account) only in a browser: there is no route for either. | |
| 230 | | [Workspaces](/reference/api/workspaces/create-workspace/) | Creating a workspace. | |
| 231 | | [Notifications](/reference/api/notifications/list-notifications/) | Your notifications: their threads, why you were told of each, marking them read, done, saved or snoozed, and what you subscribe to and watch. See [notifications](/guides/notifications/). | |
| 232 | | [Billing](/reference/api/billing/get-usage/) | A workspace's usage by product, project and day, its budget and its invoices. See [usage and billing](/guides/usage-and-billing/). | |
| 233 | | [Invites](/reference/api/invites/list-invites/) | Inviting a friend to g1t by email, inviting people into a workspace by username or email, and answering the invitations sent to you. Anyone can sign up without an invite. See [invite a friend](/guides/authentication/#invite-a-friend). | |
| 234 | | [Repositories](/reference/api/repositories/list-repos/) | A repository, how it handles pull requests, and its timeline. | |
| 235 | | [Access](/reference/api/access/list-collaborators/) | Who has which role on a repository, invitations, outside collaborators, and a workspace's base permission. | |
| 236 | | [Secret scanning](/reference/api/secret-scanning/list-secret-scanning-alerts/) | Secrets found in pushes and history, where each one is, bypassing push protection and reviewing bypass requests, validity checks, and custom patterns. See [secret protection](/guides/security/secret-protection/). | |
| 237 | | [Code scanning](/reference/api/code-scanning/list-code-scanning-alerts/) | SARIF uploads, and the alerts and analyses they make. See [code scanning](/guides/security/code-scanning/). | |
| 238 | | [Supply chain](/reference/api/supply-chain/list-vulnerability-alerts/) | Vulnerability alerts, the dependency graph, its SPDX SBOM, and comparing dependencies. See [supply chain](/guides/security/supply-chain/). | |
| 239 | | [Security settings](/reference/api/security-settings/get-security-settings/) | When pull request checks fail, dependency review's policy, delegated bypass, validity checks and a workspace's overview. | |
| 240 | | [Issues](/reference/api/issues/list-issues/) | What should change, with labels and comments. | |
| 241 | | [Pull requests](/reference/api/pull-requests/list-pull-requests/) | Proposed changes: reviews, merging and the merge queue. | |
| 242 | | [Sessions](/reference/api/sessions/read-session/) | The record of how a pull request was made, written by the coding agent that made it. See [sessions and why-blame](/guides/why-blame/). | |
| 243 | | [Actions](/reference/api/actions/list-workflows/) | Workflows, their runs and their logs. | |
| 244 | | [Run protection](/reference/api/run-protection/update-environment/) | Environments' protection rules and the reviews of the jobs they hold, approving a pull request's run from outside, a job token's default permissions, and repository dispatch. See [GitHub Actions](/guides/actions/#environments). | |
| 245 | | [Secrets and variables](/reference/api/secrets-and-variables/list-actions-secrets/) | Values workflows and deployments read. | |
| 246 | | [Webhooks](/reference/api/webhooks/list-webhooks/) | Events sent to your own address. | |
| 247 | | [Integrations](/reference/api/integrations/list-integrations/) | Alert sources and issue trackers. | |