Skip to content

MARKDOWN SOURCE

# API

Twig's versioned JSON API is rooted at `/api/v1`. It provides namespace and repository management, Git branch/content access, binary-release transfers, and namespace member/invitation operations.

## Authentication and permissions

Every API request requires an `Authorization` header—including `GET /api/version` and reads of repositories whose web pages or Git clones are public. Browser session cookies do not authenticate API requests.

Use an account username/password with HTTP Basic authentication, or a personal access token as a Bearer credential. A personal access token can also be supplied as the Basic password; its username is ignored:

```sh
curl -u "$TWIG_USERNAME:$TWIG_PASSWORD" https://twig.example/api/v1/namespaces
curl -H "Authorization: Bearer $TWIG_TOKEN" https://twig.example/api/v1/me
```

Use HTTPS when sending credentials. Tokens are scoped to namespaces and permissions. Every namespace action checks the effective permission: a token's saved grant is intersected with its owner's current namespace rights, so a token cannot exceed either. API visibility is never made public by a repository's public UI setting.

Namespace permissions used by the API:

| Permission | Operations |
| --- | --- |
| `view_namespace` | Read namespaces, repositories, branches, commits, contents, and binary assets |
| `push_changes` | Commit file changes and upload/replace binary assets |
| `create_repositories` | Create repositories in the namespace |
| `manage_repositories` | Rename, move, or delete repositories |
| `manage_namespace` | Rename/delete namespaces; a scoped token also needs this grant in an existing namespace to create another namespace |
| `manage_members` | List members/invitations and create or resend invitations |

## Identity and version

### `GET /api/v1/me`

Returns the authenticated user's public identity fields (`id`, `username`, and `email`). It never returns password hashes or token data.

### `GET /api/version`

Returns the running application version:

```json
{"version":"0.3.17"}
```

The value comes from the application package at build time. This endpoint also requires authentication.

## Namespaces and repositories

| Method | Path | Required permission |
| --- | --- | --- |
| `GET` | `/api/v1/namespaces` | `view_namespace` for each returned namespace |
| `POST` | `/api/v1/namespaces` | Existing namespace-creation policy; scoped PATs also need `manage_namespace` on a namespace in their scope |
| `GET` | `/api/v1/namespaces/{namespace}` | `view_namespace` |
| `PATCH` | `/api/v1/namespaces/{namespace}` | `manage_namespace` |
| `DELETE` | `/api/v1/namespaces/{namespace}` | `manage_namespace`; namespace must be empty |
| `GET` | `/api/v1/namespaces/{namespace}/repositories?q={text}` | `view_namespace`; `q` is an optional case-insensitive repository-name filter |
| `POST` | `/api/v1/namespaces/{namespace}/repositories` | `create_repositories` |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}` | `view_namespace` |
| `PATCH` | `/api/v1/namespaces/{namespace}/repositories/{repo}` | `manage_repositories`; rename with `{"name":"new-name"}` or move with `{"target_namespace":"other"}` |
| `DELETE` | `/api/v1/namespaces/{namespace}/repositories/{repo}` | `manage_repositories`; repository must be configured as deletable |

For example, create a repository with a chosen default branch:

```sh
curl -X POST https://twig.example/api/v1/namespaces/acme/repositories \
  -H "Authorization: Bearer $TWIG_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"tooling","default_branch":"main"}'
```

Repository creation requires an email address on the account, matching Twig's web workflow. A repository can be deleted only when its `.twig.toml` configuration has `deletable = true`.

## Branches, commits, trees, and files

| Method | Path | Required permission |
| --- | --- | --- |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}/branches` | `view_namespace` |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}/commits?ref={branch}&limit={n}` | `view_namespace` |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}/tree?ref={branch}&path={path}` | `view_namespace` |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}/contents?ref={branch}&path={path}` | `view_namespace` |
| `PUT` | `/api/v1/namespaces/{namespace}/repositories/{repo}/contents?ref={branch}&path={path}` | `push_changes` |
| `DELETE` | `/api/v1/namespaces/{namespace}/repositories/{repo}/contents?ref={branch}&path={path}` | `push_changes` |
| `POST` | `/api/v1/namespaces/{namespace}/repositories/{repo}/contents/rename` | `push_changes` |

`ref` names an exact local branch under `refs/heads/`, not an arbitrary Git revision. Slash-containing names must be URL encoded in the query string, for example `ref=feature%2Fdocs`. Content paths are repository-relative; traversal and Twig-ignored paths are refused.

Tree entries are JSON. File reads always return Base64 content, preserving arbitrary binary bytes:

```json
{
  "path": "src/main.rs",
  "reference": "main",
  "encoding": "base64",
  "content": "Zm4gbWFpbigpIHt9Cg==",
  "object_id": "…",
  "size_bytes": 13
}
```

Create or replace a file by sending JSON. `expected_head` is the current commit ID at the selected branch; stale updates return `409 Conflict` rather than overwriting newer work. `encoding` is `utf8` or `base64`. File contents are limited to 1 MiB per operation.

```sh
curl -X PUT 'https://twig.example/api/v1/namespaces/acme/repositories/tooling/contents?ref=main&path=README.md' \
  -H "Authorization: Bearer $TWIG_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from Twig API\n","encoding":"utf8","message":"Update README","expected_head":"<current-commit-id>"}'
```

Delete sends `message` and `expected_head` as a JSON body. Rename sends `ref`, `from`, `to`, `message`, and `expected_head` as a JSON body to `/contents/rename`. Mutations create normal commits on the selected branch; they do not expose arbitrary Git refs or history rewrites.

## Binary releases

| Method | Path | Required permission |
| --- | --- | --- |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}/binaries` | `view_namespace` |
| `GET` | `/api/v1/namespaces/{namespace}/repositories/{repo}/binaries/{version}/{filename}` | `view_namespace` |
| `PUT` | `/api/v1/namespaces/{namespace}/repositories/{repo}/binaries/{version}/{filename}` | `push_changes` |

Uploads use a raw `application/octet-stream` request body and return JSON. Downloads return the original bytes. Twig retains its three highest SemVer releases, supports `latest` for downloads, and enforces a 512 MiB upload ceiling and safe filenames.

```sh
curl -X PUT 'https://twig.example/api/v1/namespaces/acme/repositories/tooling/binaries/1.2.3/tool-linux-amd64' \
  -H "Authorization: Bearer $TWIG_TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @./tool-linux-amd64
```

## Members and invitations

| Method | Path | Required permission |
| --- | --- | --- |
| `GET` | `/api/v1/namespaces/{namespace}/members` | `manage_members` |
| `GET` | `/api/v1/namespaces/{namespace}/invitations` | `manage_members` |
| `POST` | `/api/v1/namespaces/{namespace}/invitations` | `manage_members` |
| `POST` | `/api/v1/namespaces/{namespace}/invitations/{id}/resend` | `manage_members` in the invitation's namespace |

Invitation creation accepts `email`, `role` (`owner` or `contributor`), and `expires` (`1d`, `7d`, `30d`, or `never`). Its response contains the invitation URL so it can be shared; the invitation token is never included in list responses. Member and invitation data is limited to the authorized namespace.

## Errors and limits

Errors are JSON with a stable code and human-readable message:

```json
{"error":{"code":"forbidden","message":"The required permission is not granted"}}
```

Common statuses are `400` for invalid input, `401` for absent/invalid credentials, `403` for insufficient permissions, `404` for missing resources, `409` for conflicts/stale branch tips, `413` for oversize payloads, and `500` for internal failures. Internal database and filesystem details are logged server-side and are not returned.

Signup/login, account settings, personal-access-token creation/revocation, database administration, test endpoints, and Git Smart HTTP are not JSON API routes. Existing UI/public Git behavior is unchanged; the authentication requirement applies to `/api/` endpoints.

## Forgejo-compatible API

Pull requests, reviews, CI runs, and the repository routes used by T3 Code and the
Forgejo and Gitea command-line tools live under `/api/v1/repos/{owner}/{repo}`,
`/api/v1/user`, and `/api/v1/version`. They use Forgejo's request and response
shapes and error body (`{"message": ...}`), and accept `Authorization: token`.
See [Pull Requests](pull-requests.md) for the endpoint table and the permission rules, [Issues](issues.md) for the issue routes, and [CI](ci.md) for the Actions routes.

API

Twig's versioned JSON API is rooted at /api/v1. It provides namespace and repository management, Git branch/content access, binary-release transfers, and namespace member/invitation operations.

Authentication and permissions

Every API request requires an Authorization header—including GET /api/version and reads of repositories whose web pages or Git clones are public. Browser session cookies do not authenticate API requests.

Use an account username/password with HTTP Basic authentication, or a personal access token as a Bearer credential. A personal access token can also be supplied as the Basic password; its username is ignored:

curl -u "$TWIG_USERNAME:$TWIG_PASSWORD" https://twig.example/api/v1/namespaces
curl -H "Authorization: Bearer $TWIG_TOKEN" https://twig.example/api/v1/me

Use HTTPS when sending credentials. Tokens are scoped to namespaces and permissions. Every namespace action checks the effective permission: a token's saved grant is intersected with its owner's current namespace rights, so a token cannot exceed either. API visibility is never made public by a repository's public UI setting.

Namespace permissions used by the API:

PermissionOperations
view_namespaceRead namespaces, repositories, branches, commits, contents, and binary assets
push_changesCommit file changes and upload/replace binary assets
create_repositoriesCreate repositories in the namespace
manage_repositoriesRename, move, or delete repositories
manage_namespaceRename/delete namespaces; a scoped token also needs this grant in an existing namespace to create another namespace
manage_membersList members/invitations and create or resend invitations

Identity and version

GET /api/v1/me

Returns the authenticated user's public identity fields (id, username, and email). It never returns password hashes or token data.

GET /api/version

Returns the running application version:

{"version":"0.3.17"}

The value comes from the application package at build time. This endpoint also requires authentication.

Namespaces and repositories

MethodPathRequired permission
GET/api/v1/namespacesview_namespace for each returned namespace
POST/api/v1/namespacesExisting namespace-creation policy; scoped PATs also need manage_namespace on a namespace in their scope
GET/api/v1/namespaces/{namespace}view_namespace
PATCH/api/v1/namespaces/{namespace}manage_namespace
DELETE/api/v1/namespaces/{namespace}manage_namespace; namespace must be empty
GET/api/v1/namespaces/{namespace}/repositories?q={text}view_namespace; q is an optional case-insensitive repository-name filter
POST/api/v1/namespaces/{namespace}/repositoriescreate_repositories
GET/api/v1/namespaces/{namespace}/repositories/{repo}view_namespace
PATCH/api/v1/namespaces/{namespace}/repositories/{repo}manage_repositories; rename with {"name":"new-name"} or move with {"target_namespace":"other"}
DELETE/api/v1/namespaces/{namespace}/repositories/{repo}manage_repositories; repository must be configured as deletable

For example, create a repository with a chosen default branch:

curl -X POST https://twig.example/api/v1/namespaces/acme/repositories \
  -H "Authorization: Bearer $TWIG_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"tooling","default_branch":"main"}'

Repository creation requires an email address on the account, matching Twig's web workflow. A repository can be deleted only when its .twig.toml configuration has deletable = true.

Branches, commits, trees, and files

MethodPathRequired permission
GET/api/v1/namespaces/{namespace}/repositories/{repo}/branchesview_namespace
GET/api/v1/namespaces/{namespace}/repositories/{repo}/commits?ref={branch}&limit={n}view_namespace
GET/api/v1/namespaces/{namespace}/repositories/{repo}/tree?ref={branch}&path={path}view_namespace
GET/api/v1/namespaces/{namespace}/repositories/{repo}/contents?ref={branch}&path={path}view_namespace
PUT/api/v1/namespaces/{namespace}/repositories/{repo}/contents?ref={branch}&path={path}push_changes
DELETE/api/v1/namespaces/{namespace}/repositories/{repo}/contents?ref={branch}&path={path}push_changes
POST/api/v1/namespaces/{namespace}/repositories/{repo}/contents/renamepush_changes

ref names an exact local branch under refs/heads/, not an arbitrary Git revision. Slash-containing names must be URL encoded in the query string, for example ref=feature%2Fdocs. Content paths are repository-relative; traversal and Twig-ignored paths are refused.

Tree entries are JSON. File reads always return Base64 content, preserving arbitrary binary bytes:

{
  "path": "src/main.rs",
  "reference": "main",
  "encoding": "base64",
  "content": "Zm4gbWFpbigpIHt9Cg==",
  "object_id": "…",
  "size_bytes": 13
}

Create or replace a file by sending JSON. expected_head is the current commit ID at the selected branch; stale updates return 409 Conflict rather than overwriting newer work. encoding is utf8 or base64. File contents are limited to 1 MiB per operation.

curl -X PUT 'https://twig.example/api/v1/namespaces/acme/repositories/tooling/contents?ref=main&path=README.md' \
  -H "Authorization: Bearer $TWIG_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from Twig API\n","encoding":"utf8","message":"Update README","expected_head":"<current-commit-id>"}'

Delete sends message and expected_head as a JSON body. Rename sends ref, from, to, message, and expected_head as a JSON body to /contents/rename. Mutations create normal commits on the selected branch; they do not expose arbitrary Git refs or history rewrites.

Binary releases

MethodPathRequired permission
GET/api/v1/namespaces/{namespace}/repositories/{repo}/binariesview_namespace
GET/api/v1/namespaces/{namespace}/repositories/{repo}/binaries/{version}/{filename}view_namespace
PUT/api/v1/namespaces/{namespace}/repositories/{repo}/binaries/{version}/{filename}push_changes

Uploads use a raw application/octet-stream request body and return JSON. Downloads return the original bytes. Twig retains its three highest SemVer releases, supports latest for downloads, and enforces a 512 MiB upload ceiling and safe filenames.

curl -X PUT 'https://twig.example/api/v1/namespaces/acme/repositories/tooling/binaries/1.2.3/tool-linux-amd64' \
  -H "Authorization: Bearer $TWIG_TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @./tool-linux-amd64

Members and invitations

MethodPathRequired permission
GET/api/v1/namespaces/{namespace}/membersmanage_members
GET/api/v1/namespaces/{namespace}/invitationsmanage_members
POST/api/v1/namespaces/{namespace}/invitationsmanage_members
POST/api/v1/namespaces/{namespace}/invitations/{id}/resendmanage_members in the invitation's namespace

Invitation creation accepts email, role (owner or contributor), and expires (1d, 7d, 30d, or never). Its response contains the invitation URL so it can be shared; the invitation token is never included in list responses. Member and invitation data is limited to the authorized namespace.

Errors and limits

Errors are JSON with a stable code and human-readable message:

{"error":{"code":"forbidden","message":"The required permission is not granted"}}

Common statuses are 400 for invalid input, 401 for absent/invalid credentials, 403 for insufficient permissions, 404 for missing resources, 409 for conflicts/stale branch tips, 413 for oversize payloads, and 500 for internal failures. Internal database and filesystem details are logged server-side and are not returned.

Signup/login, account settings, personal-access-token creation/revocation, database administration, test endpoints, and Git Smart HTTP are not JSON API routes. Existing UI/public Git behavior is unchanged; the authentication requirement applies to /api/ endpoints.

Forgejo-compatible API

Pull requests, reviews, CI runs, and the repository routes used by T3 Code and the Forgejo and Gitea command-line tools live under /api/v1/repos/{owner}/{repo}, /api/v1/user, and /api/v1/version. They use Forgejo's request and response shapes and error body ({"message": ...}), and accept Authorization: token. See Pull Requests for the endpoint table and the permission rules, Issues for the issue routes, and CI for the Actions routes.