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://git.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://git.code.storage/api/v1"
export CODE_STORAGE_TOKEN="$(node ./scripts/mint-storage-jwt.js)"
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": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Token lacks required scope: git:write",
    "details": {
      "required_scope": "git:write",
      "provided_scopes": ["git:read"]
    }
  }
}

​
Error Codes

CodeHTTP StatusDescription
INVALID_TOKEN400JWT is malformed or expired
INSUFFICIENT_PERMISSIONS401Token lacks required scope
REPOSITORY_NOT_FOUND404Repository doesn’t exist or isn’t accessible
COMMIT_NOT_FOUND404Specified commit SHA doesn’t exist
ALREADY_EXISTS409Resource already exists

​
SDK integration

Use the HTTP API with the SDK: 
import { Pierre } from '@pierre/sdk';

const pierre = new Pierre({
  key: process.env.PIERRE_PRIVATE_KEY,
});

// Create scoped token for API access
const token = pierre.createToken(
  'team/project-alpha', // Repository
  ['http:read'], // API read permissions
  Math.floor(Date.now() / 1000) + 3600, // 1-hour expiry
);

// Fetch repository data
const response = await fetch('https://git.code.storage/api/v1/repos/branches?limit=20', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

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