API access

Before you start

Sign in to your Peak workspace. For runner and run history reads, connect GitHub and keep repository access. Install Node.js 22.13 or newer to use the CLI examples.

Connect a terminal or agent

npx -y @peakinc/cli@latest login --json --no-browser --name "Build agent"

Open the printed sign-in link. Match the code and approve access within ten minutes. Read the authenticated event after approval. Add run history access when needed.

npx -y @peakinc/cli@latest login --runs

Create a token

Open Settings → API access.
Choose Create token.
Name the token.
Select the access you need.
Choose an expiry of 7, 30, or 90 days.
Create the token.
Copy it before you close the token view.
Store it in your agent’s secret manager.

Set the token through this environment variable.

PEAK_TOKEN

Use the matching scope for each task.

Scope	Use it to
workspace:read	Read your workspace, runners, runner types, and setup state; preview workflow changes.
runs:read	Read Peak run history.
audit:read	Read workspace activity.

Check which token you use before logging out. Unset the environment token to use your stored CLI login instead. Revoke the active token from the CLI.

npx -y @peakinc/cli@latest logout

Or choose Revoke beside the token in API access. Revoke CLI tokens separately from signing out of your browser.

Call the API

Send the token in the Authorization header. Use a token for API calls even when you are signed in through your browser.

curl --fail-with-body https://app.peak.inc/api/v1/workspace \
  -H "Authorization: Bearer $PEAK_TOKEN"

Use these endpoints with the listed scopes.

Method	Path	Scope	Use it to
GET	/api/v1/workspace	workspace:read	Read workspace details.
GET	/api/v1/token	Any valid token	Check the active token and scopes.
DELETE	/api/v1/token	Any valid token	Revoke the active token.
GET	/api/v1/audit-events	audit:read	Read activity.
GET	/api/v1/repositories?name=owner/repo	workspace:read	Check App visibility and pool connection.
GET	/api/v1/onboarding	workspace:read	Read setup stages and metering state.
GET	/api/v1/runners	workspace:read	Read configured runner pools.
GET	/api/v1/runner-status	workspace:read	Check current capacity by architecture.
GET	/api/v1/runner-types	workspace:read	List released runner types.
POST	/api/v1/workflow-preview	workspace:read	Preview one fixed runner label change.
POST	/api/v1/onboarding/plan	workspace:read	Plan GitHub Actions workflow changes.
GET	/api/v1/runs	runs:read	List recorded jobs.
GET	/api/v1/runs/PEAK_RUN_ID	runs:read	Read one recorded job.

Check the metering flag in setup and runner-status responses. Treat zero minute balances as disabled credits during the pilot.

{"metering_enabled": false}

For pilot run records, handle this usage state without a metered duration.

{"state": "not_metered", "duration_ms": null}

For lists of runners, runner types, runs, or activity, read the pagination fields below. Pass the next cursor as the next request’s after query parameter.

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

For run filters, use these query parameters. Use a numeric GitHub ID for the repository filter.

repository_id
branch
status
architecture
limit
after

Preview a workflow

Choose a label from the runner type catalog. Send the workflow text and job ID to the preview endpoint. Set this header for JSON requests.

Content-Type: application/json

{
  "workflow": "jobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hello\n",
  "job": "build",
  "runner_label": "RELEASED_LABEL"
}

Check the source hash before applying the returned change. Check the updated hash before applying its rollback. Read edit ranges as zero-based, end-exclusive UTF-16 string indices. Keep the decoded workflow under 128 KiB. Use workflow changes to choose between preview and setup.

Plan workflow changes

Send your repository name, default branch, released runner label, and workflow files to the planning endpoint.

{
  "repository": "your-org/your-repo",
  "default_branch": "main",
  "runner_label": "RELEASED_LABEL",
  "files": [
    {
      "path": ".github/workflows/ci.yml",
      "content": "name: CI\non: push\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hello\n"
    }
  ]
}

Send 1–20 files with at least one GitHub Actions workflow. Keep each file under 64 KiB and the JSON request body under 256 KiB. Remove hardcoded secrets before sending files. Check the returned status before using the plan.

ready
failed

Review the returned files, diffs, notes, and moved and unmoved job counts. Apply ready changes through a pull request. Read the notes if the plan fails.

Handle errors

Read the error code, message, and request ID. Keep the request ID when reporting a failed request.

{
  "error": {
    "code": "runner_unavailable",
    "message": "This runner type is not available.",
    "request_id": "REQUEST_ID"
  }
}

For a rate limit, wait for the delay in this response header before retrying.

Retry-After

Choose an API origin

Use the hosted origin by default.

https://app.peak.inc

For a local Peak instance, pass the origin explicitly.

npx -y @peakinc/cli@latest login --api-url http://localhost:3000

Or set the origin through this environment variable.

PEAK_API_URL

Use HTTPS for remote origins. Use separate credential directories for independent agent sessions. Set each directory through this environment variable.

PEAK_CONFIG_DIR

Start

Set up

Use Peak

Before you start

Connect a terminal or agent

Create a token

Call the API

Preview a workflow

Plan workflow changes

Handle errors

Choose an API origin

​Before you start

​Connect a terminal or agent

​Create a token

​Call the API

​Preview a workflow

​Plan workflow changes

​Handle errors

​Choose an API origin

Before you start

Connect a terminal or agent

Create a token

Call the API

Preview a workflow

Plan workflow changes

Handle errors

Choose an API origin