Overview

Configure HTTP requests, paginate results, and handle API errors.

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.

Each endpoint page names the scopes that the token needs, for example “Scope: git:write on the repository.” Authentication gives the rules for the scopes and for the repo claim that names the repository.

​

Base config

Set PIERRE_ORG to your organization name. For the default domain, set the API base URL as shown:

export PIERRE_ORG="your-org"
export PIERRE_API_BASE_URL="https://api.${PIERRE_ORG}.code.storage"
export PIERRE_TOKEN="YOUR_JWT_TOKEN"

If your organization uses another API hostname, use that hostname instead. Every operation path starts with /api, and the examples append it, as in $PIERRE_API_BASE_URL/api/meta. The SDKs and the CLI read the same PIERRE_API_BASE_URL, with no path.

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:

curl "$PIERRE_API_BASE_URL/api/meta" \
  -H "Authorization: Bearer $PIERRE_TOKEN"

The SDKs and the CLI also read PIERRE_TOKEN. A token in it replaces the private key, so the SDK cannot sign its own tokens, for example for a Git remote URL. Unset PIERRE_TOKEN before you run SDK code with a private key. See Create a client.

​

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.

​

Repository names in paths

A repository name can contain /, for example acme/web. In a path, encode the name as one segment: /api/repos/acme%2Fweb/branches. A name with only URL-safe characters needs no encoding. Encode the name once. The server decodes it once.

​

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:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "repository not found",
  "instance": "/api/repos/my-repo",
  "code": "repository_not_found",
  "error": "repository not found"
}

• 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.

A 400 response for a request body can name the invalid fields in invalid_params. Each item has the dotted path of the field in name and the rule that the value breaks in reason:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "default_branch must be a string",
  "code": "bad_request",
  "error": "default_branch must be a string",
  "invalid_params": [{ "name": "default_branch", "reason": "must be a string" }]
}

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:

Status	Code
400	bad_request
401	unauthorized
403	forbidden
404	not_found
405	method_not_allowed
408	request_timeout
409	conflict
412	precondition_failed
413	payload_too_large
422	unprocessable_entity
429	rate_limited
500	internal_error
501	not_implemented
502	bad_gateway
503	service_unavailable
504	gateway_timeout

Specific codes:

Status	Code	Meaning
400	repo_claim_missing	The token has no repo claim.
400	repo_name_mismatch	The request repo_name does not match the token repo claim.
403	insufficient_scope	The token does not have a scope that the operation requires.
403	hosting_not_enabled	Hosting is not enabled for your organization.
403	authentication_unavailable	The server cannot verify credentials now. Retry the request.
404	route_not_found	No API route matches the path. See /api/openapi.json.
404	repository_not_found	The repository does not exist, or the token cannot access it.
404	branch_not_found	The branch does not exist.
404	ref_not_found	The ref or revision does not exist.
404	credential_not_found	The Git credential does not exist.
404	deployment_not_found	The deployment does not exist.
404	hosting_project_not_found	The repository has no hosting project.
409	repository_deleted	The repository is already deleted.
409	repository_thawing	The repository is being restored from cold storage. Retry after Retry-After.
409	sync_in_progress	An upstream sync is in progress. Retry the request.
409	upstream_already_configured	The repository already has an upstream.
409	merge_conflict	The merge has file conflicts.
409	credential_exists	The repository already has a Git credential.
409	deployment_project_name_in_use	Another repository uses the hosting project name.
412	github_app_not_configured	No GitHub App is set up, or the App has no usable private key.
412, 4xx	github_repository_inaccessible	GitHub does not give access to the upstream repository.
422	idempotency_key_reused	The idempotency key belongs to a different request.

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.