> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Configure HTTP requests, paginate results, and handle API errors.

Use the HTTP APIs from any client that supports HTTPS. Each endpoint page defines its method, path,
parameters, responses, and required permissions.

Requests use a signed JWT in the `Authorization: Bearer` header. See
[Authentication](/docs/platform/authentication) for private keys and token signing.

## Base config

Set `PIERRE_ORG` to your organization name. For the default domain, set the API base URL as shown:

```bash theme={"theme":{"light":"github-light","dark":"min-dark"}}
export PIERRE_ORG="your-org"
export PIERRE_API_BASE_URL="https://api.${PIERRE_ORG}.code.storage/api"
export PIERRE_TOKEN="YOUR_JWT_TOKEN"
```

If your organization uses another API hostname, use that hostname instead. The `/api` suffix is the
common path prefix; the examples append paths such as `/meta` to it.

The organization settings page in the dashboard shows your exact API host and Git host. The OpenAPI
document declares the server `https://api.{org}.code.storage`. Here, `{org}` is the subdomain of
your API host, which is usually your organization name. Every operation path starts with `/api`.

Replace `YOUR_JWT_TOKEN` with a token from the
[signing examples](/docs/platform/authentication#how-to-sign-a-jwt). Send it in the `Authorization`
header:

```bash theme={"theme":{"light":"github-light","dark":"min-dark"}}
curl "$PIERRE_API_BASE_URL/meta" \
  -H "Authorization: Bearer $PIERRE_TOKEN"
```

<span id="sdk-integration" />

## Requests and responses

Use the method, path, and content types shown on the endpoint page. Responses can contain JSON, file
content, archives, or diffs.

Check the response status and content type before you read its body.

Use the current endpoints for new integrations.

## Pagination

<span id="common-parameters" />

For endpoints that support cursor pagination, use `limit` to request a page size and `cursor` to
continue a previous request. Defaults, maximum page sizes, and result fields vary by endpoint.

<span id="response-fields" />

<span id="example-generic-pagination-pattern" />

When a response includes `has_more` and `next_cursor`:

1. Read the results from the response field documented for that endpoint.
2. If `has_more` is `true`, pass `next_cursor` as the next request's `cursor`. Keep other filters
   unchanged.
3. Stop when `has_more` is `false`.

Treat cursors as opaque values. Do not construct or modify them.

## Error handling

Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details with the
`application/problem+json` content type:

```json theme={"theme":{"light":"github-light","dark":"min-dark"}}
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "repository not found",
  "instance": "/api/repos/my-repo",
  "code": "repository_not_found",
  "error": "repository not found"
}
```

* `code` is a stable, snake\_case value. Branch on `code`.
* `detail` is a message for people. Its text can change.
* `error` repeats `detail` for older clients.

Some streaming commit, note, and merge operations return an operation-specific body instead. The
OpenAPI document shows these bodies.

### Error codes

Each HTTP status has a generic code. A specific code replaces it when you must take a different
action. New codes can be added. Treat an unknown code as the generic code for its status.

Generic codes:

| Status | Code |
| - | - |
| 400 | `bad_request` |
| 401 | `unauthorized` |
| 403 | `forbidden` |
| 404 | `not_found` |
| 405 | `method_not_allowed` |
| 408 | `request_timeout` |
| 409 | `conflict` |
| 412 | `precondition_failed` |
| 413 | `payload_too_large` |
| 422 | `unprocessable_entity` |
| 429 | `rate_limited` |
| 500 | `internal_error` |
| 501 | `not_implemented` |
| 502 | `bad_gateway` |
| 503 | `service_unavailable` |
| 504 | `gateway_timeout` |

Specific codes:

| Status | Code | Meaning |
| - | - | - |
| 400 | `repo_claim_missing` | The token has no `repo` claim. |
| 400 | `repo_name_mismatch` | The request `repo_name` does not match the token `repo` claim. |
| 403 | `insufficient_scope` | The token does not have a scope that the operation requires. |
| 403 | `hosting_not_enabled` | Hosting is not enabled for your organization. |
| 403 | `authentication_unavailable` | The server cannot verify credentials now. Retry the request. |
| 404 | `route_not_found` | No API route matches the path. See `/api/openapi.json`. |
| 404 | `repository_not_found` | The repository does not exist, or the token cannot access it. |
| 404 | `branch_not_found` | The branch does not exist. |
| 404 | `ref_not_found` | The ref or revision does not exist. |
| 404 | `credential_not_found` | The Git credential does not exist. |
| 404 | `deployment_not_found` | The deployment does not exist. |
| 404 | `hosting_project_not_found` | The repository has no hosting project. |
| 409 | `repository_deleted` | The repository is already deleted. |
| 409 | `repository_thawing` | The repository is being restored from cold storage. Retry after `Retry-After`. |
| 409 | `sync_in_progress` | An upstream sync is in progress. Retry the request. |
| 409 | `upstream_already_configured` | The repository already has an upstream. |
| 409 | `merge_conflict` | The merge has file conflicts. |
| 409 | `credential_exists` | The repository already has a Git credential. |
| 409 | `deployment_project_name_in_use` | Another repository uses the hosting project name. |
| 412 | `github_app_not_configured` | Your organization does not have exactly one GitHub App. |
| 412, 4xx | `github_repository_inaccessible` | GitHub does not give access to the upstream repository. |
| 422 | `idempotency_key_reused` | The idempotency key belongs to a different request. |

`github_repository_inaccessible` uses 412, or the 4xx status that GitHub returns, for example 422.

The "Error codes" section of the OpenAPI document description has the same list.

## Resolve authentication errors

A `401` means that the request has no supported credential. A `403` with the detail
`Invalid or expired token` means that Code Storage cannot verify the token.
[Resolve token errors](/docs/platform/authentication#resolve-token-errors) lists each cause and the
`400`, `403`, and `404` responses for scopes and the `repo` claim.