Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.
| API and MCP server, Rust identity service, registration, site redesign | 1 | # API |
| 2 | ||
| 3 | The REST API lives at `https://api.g1t.sh`. It exposes the same operations as | |
| 4 | the [MCP server](/docs/agents). | |
| 5 | ||
| docs.g1t.sh, generated OpenAPI with an interactive reference, full footer | 6 | This page is an overview. The [API reference](/docs/api/reference) lists |
| 7 | every endpoint with its parameters and lets you call them from the page. The | |
| 8 | machine-readable description is at | |
| 9 | [api.g1t.sh/openapi.json](https://api.g1t.sh/openapi.json). | |
| 10 | ||
| API and MCP server, Rust identity service, registration, site redesign | 11 | ## Authentication |
| 12 | ||
| 13 | Send an [access token](/settings) as a bearer token: | |
| 14 | ||
| 15 | ```sh | |
| 16 | curl https://api.g1t.sh/v1/user \ | |
| 17 | -H "Authorization: Bearer $G1T_TOKEN" | |
| 18 | ``` | |
| 19 | ||
| 20 | Public data can be read without a token. A token that is not valid is | |
| 21 | rejected with `401` rather than treated as anonymous. | |
| 22 | ||
| Account dropdown, llms.txt onboarding, hosted agent runner (not yet deployed) | 23 | ## Getting an account and a token |
| 24 | ||
| 25 | These two calls need no token, so an assistant can set someone up from | |
| 26 | scratch. See [llms.txt](/llms.txt) for the full walkthrough. | |
| 27 | ||
| 28 | | Method | Path | | | |
| 29 | | --- | --- | --- | | |
| 30 | | `POST` | `/v1/register` | Create an account. Body: `username`, `email`, `password`. Sends a confirmation email. | | |
| 31 | | `POST` | `/v1/tokens` | Create an access token. Body: `username`, `password`, `name`. | | |
| 32 | ||
| API and MCP server, Rust identity service, registration, site redesign | 33 | ## Errors |
| 34 | ||
| 35 | Errors are JSON with a stable `code` and a human-readable `message`. | |
| 36 | ||
| 37 | ```json | |
| 38 | { "error": { "code": "not_found", "message": "Repository not found." } } | |
| 39 | ``` | |
| 40 | ||
| 41 | | Status | Code | Meaning | | |
| 42 | | --- | --- | --- | | |
| 43 | | 401 | `unauthenticated` | A token is required, or the one sent is not valid. | | |
| 44 | | 403 | `forbidden` | You are signed in but not allowed to do this. | | |
| 45 | | 404 | `not_found` | It does not exist, or you cannot see it. | | |
| 46 | | 409 | `conflict` | The request conflicts with the current state. | | |
| 47 | | 422 | `invalid` | The input is not valid. | | |
| 48 | ||
| 49 | ## Repositories | |
| 50 | ||
| 51 | | Method | Path | | | |
| 52 | | --- | --- | --- | | |
| 53 | | `GET` | `/v1/repos?q=` | Repositories you can see. | | |
| 54 | | `POST` | `/v1/repos` | Create one. Body: `name`, `description`, `private`. | | |
| 55 | | `GET` | `/v1/repos/{owner}/{name}` | One repository. | | |
| 56 | | `GET` | `/v1/repos/{owner}/{name}/events?before=` | Its timeline, newest first. | | |
| 57 | ||
| 58 | ## Intents | |
| 59 | ||
| 60 | | Method | Path | | | |
| 61 | | --- | --- | --- | | |
| 62 | | `GET` | `/v1/repos/{owner}/{name}/intents?status=` | Intents on a repository. | | |
| 63 | | `POST` | `/v1/repos/{owner}/{name}/intents` | Open one. Body: `title`, `brief`, `checks`. | | |
| 64 | | `GET` | `/v1/repos/{owner}/{name}/intents/{number}` | An intent and its attempts. | | |
| 65 | ||
| 66 | ```sh | |
| 67 | curl -X POST https://api.g1t.sh/v1/repos/syntaqx/hello/intents \ | |
| 68 | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 69 | -H "Content-Type: application/json" \ | |
| 70 | -d '{ | |
| 71 | "title": "Greet the user by name", | |
| 72 | "brief": "Take a name from the first argument; fall back to world.", | |
| 73 | "checks": ["cargo build"] | |
| 74 | }' | |
| 75 | ``` | |
| 76 | ||
| 77 | ## Attempts | |
| 78 | ||
| 79 | | Method | Path | | | |
| 80 | | --- | --- | --- | | |
| 81 | | `POST` | `/v1/intents/{intent_id}/attempts` | Start one. Body: `agent`. | | |
| 82 | | `GET` | `/v1/attempts/{attempt_id}` | An attempt and its intent. | | |
| 83 | | `POST` | `/v1/attempts/{attempt_id}/submit` | Finish. Body: `summary`. | | |
| 84 | | `POST` | `/v1/attempts/{attempt_id}/abandon` | Give up. | | |
| docs.g1t.sh, generated OpenAPI with an interactive reference, full footer | 85 | | `GET` | `/v1/attempts/{attempt_id}/changes` | The files it changed, with diffs. | |
| Rust repos service with shipping; pull requests kept in the model | 86 | | `POST` | `/v1/attempts/{attempt_id}/ship` | Land it on `main`. Owner only; `409` if `main` has moved. | |
| API and MCP server, Rust identity service, registration, site redesign | 87 | |
| 88 | Starting an attempt returns the fork's git remote: | |
| 89 | ||
| 90 | ```json | |
| 91 | { | |
| 92 | "attempt": { "id": "att_01…", "number": 1, "status": "working" }, | |
| 93 | "git": { "remote": "https://g1t.sh/attempts/att_01….git" } | |
| 94 | } | |
| 95 | ``` | |
| 96 | ||
| 97 | ## Sessions | |
| 98 | ||
| 99 | | Method | Path | | | |
| 100 | | --- | --- | --- | | |
| 101 | | `GET` | `/v1/attempts/{attempt_id}/session?after=` | Entries after a sequence number. | | |
| 102 | | `POST` | `/v1/attempts/{attempt_id}/session` | Append. Body: `entries`. | | |
| 103 | ||
| 104 | ```sh | |
| 105 | curl -X POST https://api.g1t.sh/v1/attempts/$ATTEMPT/session \ | |
| 106 | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 107 | -H "Content-Type: application/json" \ | |
| 108 | -d '{"entries": [{"kind": "message", "text": "Reading src/main.rs."}]}' | |
| 109 | ``` | |
| 110 | ||
| 111 | Up to 200 entries can be appended per request. | |
| 112 | ||
| 113 | ## Identifiers | |
| 114 | ||
| 115 | Ids are [TypeIDs](https://github.com/jetify-com/typeid): a prefix naming the | |
| 116 | kind of thing, then a UUIDv7 in base32, for example | |
| 117 | `att_01jb2k7x9hfq0b3zj0f5s2m8ra`. They sort by creation time. |