Code Storage HTTP API

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:

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:

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

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:

{
  "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:

// 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`);

Getting Started

Features

Workflows

Reference

Base config

Common Parameters

Response Fields

Error handling

Error Codes

SDK integration

​Base config

​Pagination

​Common Parameters

​Response Fields

​Example: Generic pagination pattern

​Error handling

​Error Codes

​SDK integration

Base config

Pagination

Common Parameters

Response Fields

Example: Generic pagination pattern

Error handling

Error Codes

SDK integration