API 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://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

Code	HTTP Status	Description
INVALID_TOKEN	400	JWT is malformed or expired
INSUFFICIENT_PERMISSIONS	401	Token lacks required scope
REPOSITORY_NOT_FOUND	404	Repository doesn’t exist or isn’t accessible
COMMIT_NOT_FOUND	404	Specified commit SHA doesn’t exist
ALREADY_EXISTS	409	Resource 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`);