> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peak.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# API access

> Connect agents with scoped tokens and read workspace data.

## 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

```bash theme={null}
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.

```bash theme={null}
npx -y @peakinc/cli@latest login --runs
```

## Create a token

1. Open Settings → API access.
2. Choose Create token.
3. Name the token.
4. Select the access you need.
5. Choose an expiry of 7, 30, or 90 days.
6. Create the token.
7. Copy it before you close the token view.
8. Store it in your agent's secret manager.

Set the token through this environment variable.

```text theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```json theme={null}
{"metering_enabled": false}
```

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

```json theme={null}
{"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.

```json theme={null}
{
  "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.

```text theme={null}
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.

```text theme={null}
Content-Type: application/json
```

```json theme={null}
{
  "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](/workflows) 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.

```json theme={null}
{
  "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.

```text theme={null}
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.

```json theme={null}
{
  "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.

```text theme={null}
Retry-After
```

## Choose an API origin

Use the hosted origin by default.

```text theme={null}
https://app.peak.inc
```

For a local Peak instance, pass the origin explicitly.

```bash theme={null}
npx -y @peakinc/cli@latest login --api-url http://localhost:3000
```

Or set the origin through this environment variable.

```text theme={null}
PEAK_API_URL
```

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

```text theme={null}
PEAK_CONFIG_DIR
```