API reference
Base URL: https://api.harebox.com/v1. A local build answers at http://127.0.0.1:8787/v1. The machine-readable form is openapi.yaml.
Conventions. State names are the same on every surface. Every error has code, message and, when one exists, fix. Every create accepts Idempotency-Key. Every list uses limit and cursor. Every stream resumes from its last event ID.
| Operation | Route |
|---|---|
| Get the current identity | GET /me |
| List organizations | GET /orgs |
| Create an organization | POST /orgs |
| Update organization settings | PATCH /orgs/{org} |
| Set the active organization | PATCH /orgs/active |
| List members | GET /orgs/{org}/members |
| Invite a member | POST /orgs/{org}/members |
| Change a member's role or caps | PATCH /orgs/{org}/members/{member} |
| Remove a member | DELETE /orgs/{org}/members/{member} |
| List projects | GET /projects |
| Create a project | POST /projects |
| Update a project | PATCH /projects/{project} |
| Delete an empty project | DELETE /projects/{project} |
| Register an agent without a pasted key | POST /agent-registrations |
| Start a human claim of an agent account | POST /agent-registrations/{registration}/claim |
| Get limits and what remains | GET /limits |
| Operation | Route |
|---|---|
| Get the public rate card | GET /rates |
| Show the EU region | GET /regions |
| List harnesses and models | GET /harnesses |
| Operation | Route |
|---|---|
| Get the retention policy | GET /account/data-retention |
| Update the retention policy | PATCH /account/data-retention |
| Get a deletion operation | GET /deletion-operations/{operation} |
| Get any long-running operation | GET /operations/{operation} |
| Read the audit log | GET /audit-log |
| Operation | Route |
|---|---|
| List connected repositories | GET /repos |
| Connect a repository | POST /repos |
| List environments | GET /environments |
| Create an environment | POST /environments |
| Update an environment and make a new version | PUT /environments/{environment} |
| Delete an environment | DELETE /environments/{environment} |
| Move running sandboxes to a version | POST /environments/{environment}/upgrade |
| Set a variable | PUT /environments/{environment}/vars/{key} |
| Remove a variable | DELETE /environments/{environment}/vars/{key} |
| Write a secret file | PUT /environments/{environment}/secret-files |
| Remove a secret file | DELETE /environments/{environment}/secret-files |
| Add a repository | POST /environments/{environment}/repos |
| Remove a repository | DELETE /environments/{environment}/repos/{repository} |
| Operation | Route |
|---|---|
| List API keys | GET /api-keys |
| Create a scoped API key | POST /api-keys |
| Edit a key's name, scopes, IP allowlist or budget | PATCH /api-keys/{key} |
| Revoke an API key | DELETE /api-keys/{key} |
| Rotate an API key with an overlap window | POST /api-keys/{key}/rotate |
| Get usage of an API key | GET /api-keys/{key}/usage |
| Operation | Route |
|---|---|
| List webhooks | GET /webhooks |
| Create a webhook | POST /webhooks |
| Get a webhook | GET /webhooks/{webhook} |
| Update a webhook | PATCH /webhooks/{webhook} |
| Delete a webhook | DELETE /webhooks/{webhook} |
| Rotate the signing secret with an overlap window | POST /webhooks/{webhook}/rotate |
| List delivery attempts | GET /webhooks/{webhook}/deliveries |
| Redeliver an event | POST /webhooks/{webhook}/deliveries/{delivery}/redeliver |
| Send a signed test event | POST /webhooks/{webhook}/test |
| List every event type and schema URL | GET /event-types |
| Read account events with a cursor | GET /events |
| Stream account events over SSE | GET /events/stream |
| Get the OpenTelemetry export | GET /telemetry |
| Set the OpenTelemetry export | PUT /telemetry |
| Remove the OpenTelemetry export | DELETE /telemetry |
| Operation | Route |
|---|---|
| Get CI status and connected accounts | GET /ci |
| Connect a GitHub account or org | POST /ci/connect |
| Set the policy for public repositories | POST /ci/public |
| Get a CI job | GET /ci/jobs/{job} |
| Read CI job logs | GET /ci/jobs/{job}/logs |
| Operation | Route |
|---|---|
| List credential profiles | GET /credential-profiles |
| Create a credential profile | POST /credential-profiles |
| Rename a profile or make it the default | PUT /credential-profiles/{profile} |
| Delete a credential profile | DELETE /credential-profiles/{profile} |
| Set an API key | PUT /credential-profiles/{profile}/keys/{credential} |
| Remove a credential | DELETE /credential-profiles/{profile}/keys/{credential} |
| List accounts of a credential | GET /credential-profiles/{profile}/accounts/{credential} |
| Add another key to a credential | POST /credential-profiles/{profile}/accounts/{credential} |
| Switch to another account | PUT /credential-profiles/{profile}/accounts/{credential}/{account}/active |
| Forget an account | DELETE /credential-profiles/{profile}/accounts/{credential}/{account} |
| Set a custom API | PUT /credential-profiles/{profile}/custom-apis/{name} |
| Remove a custom API | DELETE /credential-profiles/{profile}/custom-apis/{name} |
| Get the credentials proxy | GET /proxy |
| Configure the credentials proxy | PUT /proxy |
| List secret-injection rules | GET /proxy/rules |
| Add a rule binding a secret to host | POST /proxy/rules |
| Remove a rule | DELETE /proxy/rules/{rule} |
| List vault connections | GET /vault-connections |
| Connect an external vault | POST /vault-connections |
| Disconnect a vault | DELETE /vault-connections/{vault} |
| Get AI usage | GET /ai-usage |
| Get AI usage of a sandbox | GET /sandboxes/{sandbox}/ai-usage |
| Block or allow AI access or set a budget | PUT /sandboxes/{sandbox}/ai-access |
| Get the account secrets setup | GET /secrets |
| Update the account secrets setup | POST /secrets |
| Operation | Route |
|---|---|
| List sandboxes | GET /sandboxes |
| Create a sandbox, optionally from a template, and optionally queue it | POST /sandboxes |
| Create many sandboxes in one call | POST /sandboxes/batch |
| Get a sandbox | GET /sandboxes/{sandbox} |
| Update name, labels, deadline, sleep policy or subdomain | PATCH /sandboxes/{sandbox} |
| Delete a sandbox and erase its data | DELETE /sandboxes/{sandbox} |
| Sleep now and keep memory | POST /sandboxes/{sandbox}/sleep |
| Wake a sleeping sandbox | POST /sandboxes/{sandbox}/wake |
| Save the disk and release the machine | POST /sandboxes/{sandbox}/stop |
| Get a stop | GET /sandboxes/{sandbox}/stops/{stop} |
| Resume a stopped or failed sandbox | POST /sandboxes/{sandbox}/resume |
| Fork a running or stopped sandbox | POST /sandboxes/{sandbox}/fork |
| Change size live where possible | POST /sandboxes/{sandbox}/resize |
| Restore to a point in time | POST /sandboxes/{sandbox}/restore |
| Restart a machine that does not answer | POST /sandboxes/{sandbox}/recover |
| Share with the organization | POST /sandboxes/{sandbox}/share |
| Make private | POST /sandboxes/{sandbox}/unshare |
| Get the exact bill of a sandbox | GET /sandboxes/{sandbox}/usage |
| Get CPU | GET /sandboxes/{sandbox}/metrics |
| Operation | Route |
|---|---|
| Run a command: wait, stream or detach | POST /sandboxes/{sandbox}/commands |
| List the command history | GET /sandboxes/{sandbox}/commands |
| Get a command | GET /sandboxes/{sandbox}/commands/{command} |
| Signal or stop a command | DELETE /sandboxes/{sandbox}/commands/{command} |
| Attach to a command over SSE | GET /sandboxes/{sandbox}/commands/{command}/stream |
| Read command logs | GET /sandboxes/{sandbox}/commands/{command}/logs |
| List processes | GET /sandboxes/{sandbox}/processes |
| Operation | Route |
|---|---|
| Read a file | GET /sandboxes/{sandbox}/files |
| Write a file | PUT /sandboxes/{sandbox}/files |
| Delete a file | DELETE /sandboxes/{sandbox}/files |
| List a directory | GET /sandboxes/{sandbox}/files/list |
| Get file details | GET /sandboxes/{sandbox}/files/info |
| Search files by name | GET /sandboxes/{sandbox}/files/search |
| Find text in files | GET /sandboxes/{sandbox}/files/find |
| Create a directory | POST /sandboxes/{sandbox}/files/folder |
| Move or rename | POST /sandboxes/{sandbox}/files/move |
| Set permissions | POST /sandboxes/{sandbox}/files/permissions |
| Replace text in files | POST /sandboxes/{sandbox}/files/replace |
| Get a signed download URL | POST /sandboxes/{sandbox}/files/download-url |
| Get a signed upload URL | POST /sandboxes/{sandbox}/files/upload-url |
| Download a file or folder as an archive | GET /sandboxes/{sandbox}/artifacts |
| Operation | Route |
|---|---|
| Prompt a harness | POST /sandboxes/{sandbox}/prompts |
| Get a prompt | GET /sandboxes/{sandbox}/prompts/{prompt} |
| List conversations | GET /sandboxes/{sandbox}/conversations |
| Read sandbox and agent events with a cursor | GET /sandboxes/{sandbox}/events |
| Stream sandbox and agent events over SSE or WebSocket | GET /sandboxes/{sandbox}/events/stream |
| Steer a running turn | POST /sandboxes/{sandbox}/steer |
| Interrupt running work | POST /sandboxes/{sandbox}/interrupt |
| Operation | Route |
|---|---|
| Get a desktop stream URL | POST /sandboxes/{sandbox}/desktop |
| Start a screen recording | POST /sandboxes/{sandbox}/recordings |
| List recordings | GET /sandboxes/{sandbox}/recordings |
| Stop a recording | DELETE /sandboxes/{sandbox}/recordings/{recording} |
| Screenshot, click, type or scroll | POST /sandboxes/{sandbox}/computer |
| List public endpoints | GET /sandboxes/{sandbox}/endpoints |
| Expose a port | POST /sandboxes/{sandbox}/endpoints |
| Change auth, domain or title | PATCH /sandboxes/{sandbox}/endpoints/{endpoint} |
| Stop exposing a port | DELETE /sandboxes/{sandbox}/endpoints/{endpoint} |
| Rotate a URL token atomically | POST /sandboxes/{sandbox}/endpoints/{endpoint}/rotate |
| Authorize an SSH key | POST /sandboxes/{sandbox}/ssh-keys |
| Open a byte stream to a port inside a sandbox, over WebSocket: what SSH, SCP and port forwarding use | GET /sandboxes/{sandbox}/tunnel |
| Operation | Route |
|---|---|
| Get host-enforced firewall rules | GET /sandboxes/{sandbox}/firewall |
| Replace firewall rules | PUT /sandboxes/{sandbox}/firewall |
| List reserved IPs | GET /static-ips |
| Reserve an IP | POST /static-ips |
| Attach an IP to a sandbox | PUT /static-ips/{ip}/attachment |
| Release an IP | DELETE /static-ips/{ip} |
| List custom domains | GET /domains |
| Add a custom domain | POST /domains |
| Remove a custom domain | DELETE /domains/{domain} |
| List private meshes | GET /meshes |
| Create a private mesh | POST /meshes |
| Delete a private mesh | DELETE /meshes/{mesh} |
| Operation | Route |
|---|---|
| List snapshots | GET /snapshots |
| List snapshots of a sandbox | GET /sandboxes/{sandbox}/snapshots |
| Take a disk or memory snapshot now | POST /sandboxes/{sandbox}/snapshots |
| Delete all snapshots of a sandbox | DELETE /sandboxes/{sandbox}/snapshots |
| Get the latest snapshot | GET /sandboxes/{sandbox}/snapshots/latest |
| Delete a snapshot | DELETE /snapshots/{snapshot} |
| Browse a snapshot | GET /snapshots/{snapshot}/tree |
| Download a file or folder from a snapshot | GET /snapshots/{snapshot}/files |
| Get a signed archive URL | GET /snapshots/{snapshot}/download |
| Operation | Route |
|---|---|
| List templates | GET /templates |
| Save a sandbox as a new template version | POST /templates |
| Get a template and its versions | GET /templates/{template} |
| Delete a template or a version | DELETE /templates/{template} |
| List share codes | GET /templates/{template}/shares |
| Create a share code | POST /templates/{template}/shares |
| Revoke a share code | DELETE /templates/{template}/shares/{share} |
| Operation | Route |
|---|---|
| List fleets | GET /fleets |
| Create a fleet | POST /fleets |
| Get a fleet | GET /fleets/{fleet} |
| Change a fleet or scale it | PATCH /fleets/{fleet} |
| Delete a fleet and its sandboxes | DELETE /fleets/{fleet} |
| Send one prompt to every member | POST /fleets/{fleet}/prompts |
| List wake timers and schedules | GET /schedules |
| Create a wake timer or schedule | POST /schedules |
| Delete a schedule | DELETE /schedules/{schedule} |
| Operation | Route |
|---|---|
| Get the plan | GET /billing/plan |
| Change the plan | PUT /billing/plan |
| Get the wallet | GET /billing/wallet |
| Quote a top-up with its bonus | GET /billing/wallet/quote |
| Add money to the wallet | POST /billing/wallet/payments |
| Set auto top-up | PUT /billing/wallet/auto-top-up |
| Add a payment card | POST /billing/cards |
| List invoices | GET /billing/invoices |
| Get usage by project, fleet, label, member or size | GET /usage |
| Export usage per sandbox, with labels, as CSV or JSON Lines | GET /usage/export |
| List budgets | GET /budgets |
| Create a hard or soft dollar budget | POST /budgets |
| Change a budget | PATCH /budgets/{budget} |
| Delete a budget | DELETE /budgets/{budget} |
| List reservations | GET /reservations |
| Commit to capacity for one year | POST /reservations |
| Operation | Route |
|---|---|
| Forecast this month | GET /copilot/forecast |
| List savings recommendations with evidence | GET /copilot/recommendations |
| Apply a recommendation | POST /copilot/recommendations/{recommendation}/apply |