Skip to main content
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/v1
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/v1"
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/v1/repos/branches?limit=20', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

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