CI endpoints

All paths below are relative to https://berrybox.io/api/management/v1. The API key selects the team. Write scopes do not override role checks.

Read CI state

These operations require ci:read:

An HTTP wait accepts 1–25 seconds. The CLI combines bounded waits for a longer user-facing timeout; it does not busy-poll status. Concurrent wait limits apply.

Log queries use literal search text of at most 200 characters, offsets up to 1,000,000 and limits of 1–200 lines. The fetched log is bounded to 2 MiB. GitHub may not publish logs until after a step or job finishes; missing logs are not an empty successful result.

Change runner settings

PATCH /ci/settings requires ci:write and a permitted team role. Fetch current settings first, then send its expectedRevision with the complete settings you intend to keep:

{
  "expectedRevision": 1,
  "enabledLabels": ["berrybox-2vcpu-ubuntu-2404"],
  "aliases": {},
  "concurrencyVcpu": 4,
  "retryInterruptedJobs": false
}

Replace the example revision with the current value. A stale revision returns a conflict. Settings still obey plan and capacity ceilings. DELETE /ci/github uses the current expectedBindingVersion and requires ci:write plus the appropriate role.

Billing

Financial access also requires a permitted team role. Budget changes require an owner or admin, even when a key has billing:write.

Change a monthly budget

Read GET /ci/budget first. Send PATCH /ci/budget with an Idempotency-Key header and the current revision as a decimal string:

{
  "expectedRevision": "1",
  "budgetMicros": "100000000"
}

This example sets $100 for the month. Replace the revision with the value you read. budgetMicros: null removes the budget; "0" blocks new work. An optional thresholds array configures budget alert percentages; preserve the current values unless you mean to change them. Reuse the same idempotency key and body after an uncertain response. A revision conflict requires reading the latest state.

Top up credit

A top-up request contains amountUsd as a decimal string and a stable requestKey:

{
  "amountUsd": "20.00",
  "requestKey": "your-unique-checkout-request-id"
}

Keep the same request key when retrying an uncertain Checkout response. A successful request returns a hosted link, not paid credit. A person completes Stripe Checkout; credit is added only after verified payment confirmation.

Subscribe or manage payment details

POST /ci/billing/subscription-checkout takes { "requestKey": "your-unique-subscription-request-id" }. Preserve the same request key on an uncertain retry. A confirmed paid invoice activates Build and credits its allowance.

POST /ci/billing/subscription/cancel and POST /ci/billing/portal take no request body. Cancellation stops renewal at the end of the paid period; the portal returns a hosted browser link.

Safe automation

Keep tokens out of logs, shell arguments and agent context. Retry safe reads with backoff. For writes, honor the operation's revision and idempotency requirements. Do not invent a new request key just because a request timed out.

CLI commands · MCP setup · Billing model