Skip to main content
Use the HTTP APIs from any client that supports HTTPS. Each endpoint page defines its method, path, parameters, responses, and required permissions. Requests use a signed JWT in the Authorization: Bearer header. See Authentication for private keys and token signing.

​
Base config

Set PIERRE_ORG to your organization name. For the default domain, set the API base URL as shown:
If your organization uses another API hostname, use that hostname instead. The /api suffix is the common path prefix; the examples append paths such as /meta to it. The organization settings page in the dashboard shows your exact API host and Git host. The OpenAPI document declares the server https://api.{org}.code.storage. Here, {org} is the subdomain of your API host, which is usually your organization name. Every operation path starts with /api. Replace YOUR_JWT_TOKEN with a token from the signing examples. Send it in the Authorization header:

​
Requests and responses

Use the method, path, and content types shown on the endpoint page. Responses can contain JSON, file content, archives, or diffs. Check the response status and content type before you read its body. Use the current endpoints for new integrations.

​
Pagination

For endpoints that support cursor pagination, use limit to request a page size and cursor to continue a previous request. Defaults, maximum page sizes, and result fields vary by endpoint. When a response includes has_more and next_cursor:
  1. Read the results from the response field documented for that endpoint.
  2. If has_more is true, pass next_cursor as the next request’s cursor. Keep other filters unchanged.
  3. Stop when has_more is false.
Treat cursors as opaque values. Do not construct or modify them.

​
Error handling

Errors use RFC 9457 problem details with the application/problem+json content type:
  • code is a stable, snake_case value. Branch on code.
  • detail is a message for people. Its text can change.
  • error repeats detail for older clients.
Some streaming commit, note, and merge operations return an operation-specific body instead. The OpenAPI document shows these bodies.

​
Error codes

Each HTTP status has a generic code. A specific code replaces it when you must take a different action. New codes can be added. Treat an unknown code as the generic code for its status. Generic codes: Specific codes: github_repository_inaccessible uses 412, or the 4xx status that GitHub returns, for example 422. The “Error codes” section of the OpenAPI document description has the same list.

​
Resolve authentication errors

A 401 means that the request has no supported credential. A 403 with the detail Invalid or expired token means that Code Storage cannot verify the token. Resolve token errors lists each cause and the 400, 403, and 404 responses for scopes and the repo claim.