g1t/apps/docs/src/content/docs/reference/api.md
| 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 that |
| 8 | does 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) as a bearer token: |
| 44 | |
| 45 | ```sh |
| 46 | curl https://api.g1t.sh/user \ |
| 47 | -H "Authorization: Bearer $G1T_TOKEN" |
| 48 | ``` |
| 49 | |
| 50 | Public data can be read without a token. A token that is not valid is |
| 51 | rejected with `401` rather than treated as anonymous. Each endpoint's page |
| 52 | says whether it needs a token. |
| 53 | |
| 54 | A [workspace's own token](/guides/workspaces/#workspace-access-tokens) acts |
| 55 | as the workspace. The token a g1t agent works with can use only the |
| 56 | operations its task needs, in its own repository. |
| 57 | |
| 58 | ## Signing in from a tool |
| 59 | |
| 60 | A tool gets a token by having a person approve a short code in their |
| 61 | browser: [start signing in](/reference/api/accounts/device-code/), then |
| 62 | [finish signing in](/reference/api/accounts/device-token/). See |
| 63 | [signing in from a tool](/guides/authentication/#signing-in-from-a-tool). |
| 64 | |
| 65 | Applications that can open a browser use OAuth instead. See |
| 66 | [signing in with OAuth](/guides/authentication/#signing-in-with-oauth). |
| 67 | |
| 68 | | Method | Path | | |
| 69 | | --- | --- | --- | |
| 70 | | `GET` | `/.well-known/oauth-authorization-server` | Where the endpoints are. | |
| 71 | | `POST` | `/oauth/register` | Register a client. Body: `client_name`, `redirect_uris`. | |
| 72 | | `POST` | `/oauth/token` | Exchange a code, or refresh. Form-encoded or JSON. | |
| 73 | |
| 74 | Accounts are created in a browser only. There is no registration endpoint |
| 75 | for accounts. |
| 76 | |
| 77 | ## Requests and responses |
| 78 | |
| 79 | Request bodies are JSON. |
| 80 | |
| 81 | Every name in a body is `snake_case`, both ways: responses, errors, MCP |
| 82 | results and [webhook](/guides/webhooks/) payloads. Request bodies take the |
| 83 | same names as the MCP tools, and also accept the `camelCase` spelling: |
| 84 | |
| 85 | ```sh |
| 86 | # Both turn off counting agents' approvals. |
| 87 | curl -X PATCH https://api.g1t.sh/repos/syntaqx/hello/settings \ |
| 88 | -H "Authorization: Bearer $G1T_TOKEN" -d '{"count_agent_approvals": false}' |
| 89 | curl -X PATCH https://api.g1t.sh/repos/syntaqx/hello/settings \ |
| 90 | -H "Authorization: Bearer $G1T_TOKEN" -d '{"countAgentApprovals": false}' |
| 91 | ``` |
| 92 | |
| 93 | When a body gives a field both ways, the `snake_case` one is used. |
| 94 | |
| 95 | Names you chose are never changed: a workflow's `inputs`, the names of |
| 96 | secrets and variables, an environment's `env`, a job's `outputs` and |
| 97 | `matrix`, labels and headers come back exactly as they were written. |
| 98 | |
| 99 | A successful request answers `200` with the result as the body: an object, |
| 100 | a list, or `true` for a deletion. There is no envelope around it. |
| 101 | |
| 102 | In paths, `{owner}` is the workspace that owns the repository and `{name}` |
| 103 | is the repository's name. Issues and pull requests are addressed by |
| 104 | `{number}`; the two share one sequence of numbers per repository, so a |
| 105 | number names exactly one of them. |
| 106 | |
| 107 | ## Errors |
| 108 | |
| 109 | Errors are JSON with a stable `code` and a human-readable `message`. |
| 110 | |
| 111 | ```json |
| 112 | { "error": { "code": "not_found", "message": "Repository not found." } } |
| 113 | ``` |
| 114 | |
| 115 | | Status | Code | Meaning | |
| 116 | | --- | --- | --- | |
| 117 | | 401 | `unauthenticated` | A token is required, or the one sent is not valid. | |
| 118 | | 402 | `payment_required` | The workspace has no agent credit. Only endpoints that start an agent answer this. See [usage and billing](/guides/usage-and-billing/#when-credit-runs-out). | |
| 119 | | 403 | `forbidden` | You are signed in but not allowed to do this. | |
| 120 | | 404 | `not_found` | It does not exist, or you cannot see it. A path that is not an endpoint answers this too. | |
| 121 | | 409 | `conflict` | The request conflicts with the current state. | |
| 122 | | 422 | `invalid` | The input is not valid. | |
| 123 | |
| 124 | Branch on `code`, not on `message`: messages are written for people and |
| 125 | may change. |
| 126 | |
| 127 | ## Lists |
| 128 | |
| 129 | Lists come newest first, unless an endpoint says otherwise. Most return |
| 130 | everything up to a limit; the few that grow without bound take a cursor: |
| 131 | |
| 132 | | Endpoint | Limit | Next page | |
| 133 | | --- | --- | --- | |
| 134 | | [List repositories](/reference/api/repositories/list-repos/) | 50 | None | |
| 135 | | [List issues](/reference/api/issues/list-issues/) | 100 | None | |
| 136 | | [List pull requests](/reference/api/pull-requests/list-pull-requests/) | 100 | None | |
| 137 | | [List repository events](/reference/api/repositories/list-events/) | 50 | `before`: the id of the last event you have | |
| 138 | | [List workflow runs](/reference/api/actions/list-workflow-runs/) | `per_page`, at most 100 and 50 if not given | None | |
| 139 | | [List webhook deliveries](/reference/api/webhooks/list-webhook-deliveries/) | 50 | None | |
| 140 | | [Read a session](/reference/api/sessions/read-session/) | None | `after`: the last `seq` you have | |
| 141 | | [Get a job's log](/reference/api/actions/get-job-logs/) | 500 chunks | `after`: the last `seq` you have | |
| 142 | |
| 143 | ## Identifiers and times |
| 144 | |
| 145 | Issues and pull requests are addressed by repository and number. Other ids |
| 146 | are [TypeIDs](https://github.com/jetify-com/typeid): a prefix naming the |
| 147 | kind of thing, then a UUIDv7 in base32, for example |
| 148 | `pr_01jb2k7x9hfq0b3zj0f5s2m8ra`. They sort by creation time. |
| 149 | |
| 150 | Times are RFC 3339 in UTC, with milliseconds, such as |
| 151 | `2026-10-01T18:04:11.482Z`. |
| 152 | |
| 153 | ## Resources |
| 154 | |
| 155 | | Resource | | |
| 156 | | --- | --- | |
| 157 | | [Accounts](/reference/api/accounts/whoami/) | Signing in from a tool, and who a token acts as. | |
| 158 | | [Workspaces](/reference/api/workspaces/create-workspace/) | Creating a workspace. | |
| 159 | | [Repositories](/reference/api/repositories/list-repos/) | A repository, how it handles pull requests, and its timeline. | |
| 160 | | [Issues](/reference/api/issues/list-issues/) | What should change, with labels and comments, and assigning it to the g1t agent. | |
| 161 | | [Plans](/reference/api/plans/plan-work/) | An [outcome](/guides/outcomes/) turned into issues. | |
| 162 | | [Pull requests](/reference/api/pull-requests/list-pull-requests/) | Proposed changes: reviews, merging, the merge queue, and messages to the agent at work. | |
| 163 | | [Sessions](/reference/api/sessions/read-session/) | The record of how a pull request was made. | |
| 164 | | [Actions](/reference/api/actions/list-workflows/) | Workflows, their runs and their logs. | |
| 165 | | [Secrets and variables](/reference/api/secrets-and-variables/list-actions-secrets/) | Values workflows and deployments read. | |
| 166 | | [Webhooks](/reference/api/webhooks/list-webhooks/) | Events sent to your own address. | |
| 167 | | [Integrations](/reference/api/integrations/list-integrations/) | Model providers, alert sources and issue trackers. | |