> ## 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

The Code Storage HTTP API mirrors the SDK’s primitives over plain HTTPS, so any runtime can mint JWT-backed remotes, paginate branches and commits, stream diffs, or create new commits without a local git client.

## Base config

Every client starts by configuring the base API URL and a signed JWT.

```
Base URL: https://api.{org}.code.storage/api
Authentication: Bearer YOUR_JWT_TOKEN
```

With that reference info defined, export the concrete values for your workspace or CI runner:

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

Then talk to any endpoint with a single cURL:

```bash theme={"theme":{"light":"github-light","dark":"min-dark"}}
curl "$CODE_STORAGE_BASE_URL/repos" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json"
```

## Pagination

The API uses cursor-based pagination for list endpoints. This provides efficient and consistent traversal of large result sets.

### Common Parameters

* `cursor` (optional): Pagination cursor from previous response
* `limit` (optional): Results per page (default: 20, max: 100)

### Response Fields

* `next_cursor`: Use this value as the `cursor` parameter for the next request (surfaced as `nextCursor` in the SDK)
* `has_more`: Boolean indicating if more results are available (surfaced as `hasMore` in the SDK)

### Example: Generic pagination pattern

```js theme={"theme":{"light":"github-light","dark":"min-dark"}}
async function paginateEndpoint(url, token) {
  const results = [];
  let cursor = '';
  let hasMore = true;

  while (hasMore) {
    const params = new URLSearchParams({ limit: '20' });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(`${url}?${params}`, {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    const data = await response.json();
    results.push(...data.items); // Replace 'items' with actual field name
    cursor = data.next_cursor;
    hasMore = data.has_more;
  }

  return results;
}
```

## Error handling

All API errors follow a consistent format:

```json theme={"theme":{"light":"github-light","dark":"min-dark"}}
{
  "error": "insufficient permissions"
}
```

### Error Codes

The REST API returns a plain `error` string plus the HTTP status code. Error strings are not
guaranteed to be stable, so clients should branch on status codes rather than parsing the message.

## SDK integration

Use the HTTP API with any JWT signer (or the Python helper) and standard `fetch`:

```js theme={"theme":{"light":"github-light","dark":"min-dark"}}
// Fetch repository data (JWT must include the repo claim and git:read scope)
const response = await fetch('https://api.your-org.code.storage/api/repos/my-repo/branches?limit=20', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const { branches } = await response.json();
console.log(`Found ${branches.length} branches`);
```