# 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`](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.

## Account

| Operation | Route |
|---|---|
| [Get the current identity](api/getMe.html) | `GET /me` |
| [List organizations](api/listOrgs.html) | `GET /orgs` |
| [Create an organization](api/createOrg.html) | `POST /orgs` |
| [Update organization settings](api/updateOrg.html) | `PATCH /orgs/{org}` |
| [Set the active organization](api/setActiveOrg.html) | `PATCH /orgs/active` |
| [List members](api/listMembers.html) | `GET /orgs/{org}/members` |
| [Invite a member](api/inviteMember.html) | `POST /orgs/{org}/members` |
| [Change a member's role or caps](api/updateMember.html) | `PATCH /orgs/{org}/members/{member}` |
| [Remove a member](api/removeMember.html) | `DELETE /orgs/{org}/members/{member}` |
| [List projects](api/listProjects.html) | `GET /projects` |
| [Create a project](api/createProject.html) | `POST /projects` |
| [Update a project](api/updateProject.html) | `PATCH /projects/{project}` |
| [Delete an empty project](api/deleteProject.html) | `DELETE /projects/{project}` |
| [Register an agent without a pasted key](api/registerAgent.html) | `POST /agent-registrations` |
| [Start a human claim of an agent account](api/claimAgent.html) | `POST /agent-registrations/{registration}/claim` |
| [Get limits and what remains](api/getLimits.html) | `GET /limits` |

## Catalog

| Operation | Route |
|---|---|
| [Get the public rate card](api/getRates.html) | `GET /rates` |
| [Show the EU region](api/listRegions.html) | `GET /regions` |
| [List harnesses and models](api/listHarnesses.html) | `GET /harnesses` |

## Data

| Operation | Route |
|---|---|
| [Get the retention policy](api/getRetention.html) | `GET /account/data-retention` |
| [Update the retention policy](api/updateRetention.html) | `PATCH /account/data-retention` |
| [Get a deletion operation](api/getDeletion.html) | `GET /deletion-operations/{operation}` |
| [Get any long-running operation](api/getOperation.html) | `GET /operations/{operation}` |
| [Read the audit log](api/listAuditLog.html) | `GET /audit-log` |

## Environments

| Operation | Route |
|---|---|
| [List connected repositories](api/listRepos.html) | `GET /repos` |
| [Connect a repository](api/selectRepo.html) | `POST /repos` |
| [List environments](api/listEnvironments.html) | `GET /environments` |
| [Create an environment](api/createEnvironment.html) | `POST /environments` |
| [Update an environment and make a new version](api/updateEnvironment.html) | `PUT /environments/{environment}` |
| [Delete an environment](api/deleteEnvironment.html) | `DELETE /environments/{environment}` |
| [Move running sandboxes to a version](api/upgradeEnvironment.html) | `POST /environments/{environment}/upgrade` |
| [Set a variable](api/setEnvironmentVar.html) | `PUT /environments/{environment}/vars/{key}` |
| [Remove a variable](api/deleteEnvironmentVar.html) | `DELETE /environments/{environment}/vars/{key}` |
| [Write a secret file](api/setEnvironmentSecretFile.html) | `PUT /environments/{environment}/secret-files` |
| [Remove a secret file](api/deleteEnvironmentSecretFile.html) | `DELETE /environments/{environment}/secret-files` |
| [Add a repository](api/addEnvironmentRepo.html) | `POST /environments/{environment}/repos` |
| [Remove a repository](api/deleteEnvironmentRepo.html) | `DELETE /environments/{environment}/repos/{repository}` |

## Keys

| Operation | Route |
|---|---|
| [List API keys](api/listApiKeys.html) | `GET /api-keys` |
| [Create a scoped API key](api/createApiKey.html) | `POST /api-keys` |
| [Edit a key's name, scopes, IP allowlist or budget](api/updateApiKey.html) | `PATCH /api-keys/{key}` |
| [Revoke an API key](api/revokeApiKey.html) | `DELETE /api-keys/{key}` |
| [Rotate an API key with an overlap window](api/rotateApiKey.html) | `POST /api-keys/{key}/rotate` |
| [Get usage of an API key](api/getApiKeyUsage.html) | `GET /api-keys/{key}/usage` |

## Events

| Operation | Route |
|---|---|
| [List webhooks](api/listWebhooks.html) | `GET /webhooks` |
| [Create a webhook](api/createWebhook.html) | `POST /webhooks` |
| [Get a webhook](api/getWebhook.html) | `GET /webhooks/{webhook}` |
| [Update a webhook](api/updateWebhook.html) | `PATCH /webhooks/{webhook}` |
| [Delete a webhook](api/deleteWebhook.html) | `DELETE /webhooks/{webhook}` |
| [Rotate the signing secret with an overlap window](api/rotateWebhookSecret.html) | `POST /webhooks/{webhook}/rotate` |
| [List delivery attempts](api/listDeliveries.html) | `GET /webhooks/{webhook}/deliveries` |
| [Redeliver an event](api/redeliver.html) | `POST /webhooks/{webhook}/deliveries/{delivery}/redeliver` |
| [Send a signed test event](api/testWebhook.html) | `POST /webhooks/{webhook}/test` |
| [List every event type and schema URL](api/listEventTypes.html) | `GET /event-types` |
| [Read account events with a cursor](api/listOrgEvents.html) | `GET /events` |
| [Stream account events over SSE](api/streamOrgEvents.html) | `GET /events/stream` |
| [Get the OpenTelemetry export](api/getTelemetry.html) | `GET /telemetry` |
| [Set the OpenTelemetry export](api/setTelemetry.html) | `PUT /telemetry` |
| [Remove the OpenTelemetry export](api/deleteTelemetry.html) | `DELETE /telemetry` |

## CI

| Operation | Route |
|---|---|
| [Get CI status and connected accounts](api/getCi.html) | `GET /ci` |
| [Connect a GitHub account or org](api/connectCi.html) | `POST /ci/connect` |
| [Set the policy for public repositories](api/setCiPublic.html) | `POST /ci/public` |
| [Get a CI job](api/getCiJob.html) | `GET /ci/jobs/{job}` |
| [Read CI job logs](api/getCiJobLogs.html) | `GET /ci/jobs/{job}/logs` |

## Credentials

| Operation | Route |
|---|---|
| [List credential profiles](api/listCredentialProfiles.html) | `GET /credential-profiles` |
| [Create a credential profile](api/createCredentialProfile.html) | `POST /credential-profiles` |
| [Rename a profile or make it the default](api/updateCredentialProfile.html) | `PUT /credential-profiles/{profile}` |
| [Delete a credential profile](api/deleteCredentialProfile.html) | `DELETE /credential-profiles/{profile}` |
| [Set an API key](api/setCredentialKey.html) | `PUT /credential-profiles/{profile}/keys/{credential}` |
| [Remove a credential](api/deleteCredentialKey.html) | `DELETE /credential-profiles/{profile}/keys/{credential}` |
| [List accounts of a credential](api/listCredentialAccounts.html) | `GET /credential-profiles/{profile}/accounts/{credential}` |
| [Add another key to a credential](api/addCredentialAccount.html) | `POST /credential-profiles/{profile}/accounts/{credential}` |
| [Switch to another account](api/switchCredentialAccount.html) | `PUT /credential-profiles/{profile}/accounts/{credential}/{account}/active` |
| [Forget an account](api/forgetCredentialAccount.html) | `DELETE /credential-profiles/{profile}/accounts/{credential}/{account}` |
| [Set a custom API](api/setCustomApi.html) | `PUT /credential-profiles/{profile}/custom-apis/{name}` |
| [Remove a custom API](api/deleteCustomApi.html) | `DELETE /credential-profiles/{profile}/custom-apis/{name}` |
| [Get the credentials proxy](api/getProxy.html) | `GET /proxy` |
| [Configure the credentials proxy](api/setProxy.html) | `PUT /proxy` |
| [List secret-injection rules](api/listProxyRules.html) | `GET /proxy/rules` |
| [Add a rule binding a secret to host](api/createProxyRule.html) | `POST /proxy/rules` |
| [Remove a rule](api/deleteProxyRule.html) | `DELETE /proxy/rules/{rule}` |
| [List vault connections](api/listVaults.html) | `GET /vault-connections` |
| [Connect an external vault](api/createVault.html) | `POST /vault-connections` |
| [Disconnect a vault](api/deleteVault.html) | `DELETE /vault-connections/{vault}` |
| [Get AI usage](api/getAiUsage.html) | `GET /ai-usage` |
| [Get AI usage of a sandbox](api/getSandboxAiUsage.html) | `GET /sandboxes/{sandbox}/ai-usage` |
| [Block or allow AI access or set a budget](api/setSandboxAiAccess.html) | `PUT /sandboxes/{sandbox}/ai-access` |
| [Get the account secrets setup](api/getSecretsSetup.html) | `GET /secrets` |
| [Update the account secrets setup](api/updateSecretsSetup.html) | `POST /secrets` |

## Sandboxes

| Operation | Route |
|---|---|
| [List sandboxes](api/listSandboxes.html) | `GET /sandboxes` |
| [Create a sandbox, optionally from a template, and optionally queue it](api/createSandbox.html) | `POST /sandboxes` |
| [Create many sandboxes in one call](api/createSandboxBatch.html) | `POST /sandboxes/batch` |
| [Get a sandbox](api/getSandbox.html) | `GET /sandboxes/{sandbox}` |
| [Update name, labels, deadline, sleep policy or subdomain](api/updateSandbox.html) | `PATCH /sandboxes/{sandbox}` |
| [Delete a sandbox and erase its data](api/deleteSandbox.html) | `DELETE /sandboxes/{sandbox}` |
| [Sleep now and keep memory](api/sleepSandbox.html) | `POST /sandboxes/{sandbox}/sleep` |
| [Wake a sleeping sandbox](api/wakeSandbox.html) | `POST /sandboxes/{sandbox}/wake` |
| [Save the disk and release the machine](api/stopSandbox.html) | `POST /sandboxes/{sandbox}/stop` |
| [Get a stop](api/getStop.html) | `GET /sandboxes/{sandbox}/stops/{stop}` |
| [Resume a stopped or failed sandbox](api/resumeSandbox.html) | `POST /sandboxes/{sandbox}/resume` |
| [Fork a running or stopped sandbox](api/forkSandbox.html) | `POST /sandboxes/{sandbox}/fork` |
| [Change size live where possible](api/resizeSandbox.html) | `POST /sandboxes/{sandbox}/resize` |
| [Restore to a point in time](api/restoreSandbox.html) | `POST /sandboxes/{sandbox}/restore` |
| [Restart a machine that does not answer](api/recoverSandbox.html) | `POST /sandboxes/{sandbox}/recover` |
| [Share with the organization](api/shareSandbox.html) | `POST /sandboxes/{sandbox}/share` |
| [Make private](api/unshareSandbox.html) | `POST /sandboxes/{sandbox}/unshare` |
| [Get the exact bill of a sandbox](api/getSandboxUsage.html) | `GET /sandboxes/{sandbox}/usage` |
| [Get CPU](api/getSandboxMetrics.html) | `GET /sandboxes/{sandbox}/metrics` |

## Commands

| Operation | Route |
|---|---|
| [Run a command: wait, stream or detach](api/runCommand.html) | `POST /sandboxes/{sandbox}/commands` |
| [List the command history](api/listCommands.html) | `GET /sandboxes/{sandbox}/commands` |
| [Get a command](api/getCommand.html) | `GET /sandboxes/{sandbox}/commands/{command}` |
| [Signal or stop a command](api/signalCommand.html) | `DELETE /sandboxes/{sandbox}/commands/{command}` |
| [Attach to a command over SSE](api/streamCommand.html) | `GET /sandboxes/{sandbox}/commands/{command}/stream` |
| [Read command logs](api/getCommandLogs.html) | `GET /sandboxes/{sandbox}/commands/{command}/logs` |
| [List processes](api/listProcesses.html) | `GET /sandboxes/{sandbox}/processes` |

## Files

| Operation | Route |
|---|---|
| [Read a file](api/readFile.html) | `GET /sandboxes/{sandbox}/files` |
| [Write a file](api/writeFile.html) | `PUT /sandboxes/{sandbox}/files` |
| [Delete a file](api/deleteFile.html) | `DELETE /sandboxes/{sandbox}/files` |
| [List a directory](api/listFiles.html) | `GET /sandboxes/{sandbox}/files/list` |
| [Get file details](api/statFile.html) | `GET /sandboxes/{sandbox}/files/info` |
| [Search files by name](api/searchFiles.html) | `GET /sandboxes/{sandbox}/files/search` |
| [Find text in files](api/grepFiles.html) | `GET /sandboxes/{sandbox}/files/find` |
| [Create a directory](api/makeFolder.html) | `POST /sandboxes/{sandbox}/files/folder` |
| [Move or rename](api/moveFile.html) | `POST /sandboxes/{sandbox}/files/move` |
| [Set permissions](api/chmodFile.html) | `POST /sandboxes/{sandbox}/files/permissions` |
| [Replace text in files](api/replaceInFiles.html) | `POST /sandboxes/{sandbox}/files/replace` |
| [Get a signed download URL](api/createDownloadUrl.html) | `POST /sandboxes/{sandbox}/files/download-url` |
| [Get a signed upload URL](api/createUploadUrl.html) | `POST /sandboxes/{sandbox}/files/upload-url` |
| [Download a file or folder as an archive](api/downloadArtifact.html) | `GET /sandboxes/{sandbox}/artifacts` |

## Agents

| Operation | Route |
|---|---|
| [Prompt a harness](api/createPrompt.html) | `POST /sandboxes/{sandbox}/prompts` |
| [Get a prompt](api/getPrompt.html) | `GET /sandboxes/{sandbox}/prompts/{prompt}` |
| [List conversations](api/listConversations.html) | `GET /sandboxes/{sandbox}/conversations` |
| [Read sandbox and agent events with a cursor](api/listAgentEvents.html) | `GET /sandboxes/{sandbox}/events` |
| [Stream sandbox and agent events over SSE or WebSocket](api/streamAgentEvents.html) | `GET /sandboxes/{sandbox}/events/stream` |
| [Steer a running turn](api/steerAgent.html) | `POST /sandboxes/{sandbox}/steer` |
| [Interrupt running work](api/interruptAgent.html) | `POST /sandboxes/{sandbox}/interrupt` |

## Access

| Operation | Route |
|---|---|
| [Get a desktop stream URL](api/createDesktop.html) | `POST /sandboxes/{sandbox}/desktop` |
| [Start a screen recording](api/createRecording.html) | `POST /sandboxes/{sandbox}/recordings` |
| [List recordings](api/listRecordings.html) | `GET /sandboxes/{sandbox}/recordings` |
| [Stop a recording](api/stopRecording.html) | `DELETE /sandboxes/{sandbox}/recordings/{recording}` |
| [Screenshot, click, type or scroll](api/computerAction.html) | `POST /sandboxes/{sandbox}/computer` |
| [List public endpoints](api/listEndpoints.html) | `GET /sandboxes/{sandbox}/endpoints` |
| [Expose a port](api/createEndpoint.html) | `POST /sandboxes/{sandbox}/endpoints` |
| [Change auth, domain or title](api/updateEndpoint.html) | `PATCH /sandboxes/{sandbox}/endpoints/{endpoint}` |
| [Stop exposing a port](api/deleteEndpoint.html) | `DELETE /sandboxes/{sandbox}/endpoints/{endpoint}` |
| [Rotate a URL token atomically](api/rotateEndpointToken.html) | `POST /sandboxes/{sandbox}/endpoints/{endpoint}/rotate` |
| [Authorize an SSH key](api/addSshKey.html) | `POST /sandboxes/{sandbox}/ssh-keys` |
| [Open a byte stream to a port inside a sandbox, over WebSocket: what SSH, SCP and port forwarding use](api/openTunnel.html) | `GET /sandboxes/{sandbox}/tunnel` |

## Network

| Operation | Route |
|---|---|
| [Get host-enforced firewall rules](api/getFirewall.html) | `GET /sandboxes/{sandbox}/firewall` |
| [Replace firewall rules](api/setFirewall.html) | `PUT /sandboxes/{sandbox}/firewall` |
| [List reserved IPs](api/listStaticIps.html) | `GET /static-ips` |
| [Reserve an IP](api/reserveStaticIp.html) | `POST /static-ips` |
| [Attach an IP to a sandbox](api/attachStaticIp.html) | `PUT /static-ips/{ip}/attachment` |
| [Release an IP](api/releaseStaticIp.html) | `DELETE /static-ips/{ip}` |
| [List custom domains](api/listDomains.html) | `GET /domains` |
| [Add a custom domain](api/addDomain.html) | `POST /domains` |
| [Remove a custom domain](api/deleteDomain.html) | `DELETE /domains/{domain}` |
| [List private meshes](api/listMeshes.html) | `GET /meshes` |
| [Create a private mesh](api/createMesh.html) | `POST /meshes` |
| [Delete a private mesh](api/deleteMesh.html) | `DELETE /meshes/{mesh}` |

## Snapshots

| Operation | Route |
|---|---|
| [List snapshots](api/listAllSnapshots.html) | `GET /snapshots` |
| [List snapshots of a sandbox](api/listSnapshots.html) | `GET /sandboxes/{sandbox}/snapshots` |
| [Take a disk or memory snapshot now](api/createSnapshot.html) | `POST /sandboxes/{sandbox}/snapshots` |
| [Delete all snapshots of a sandbox](api/deleteSandboxSnapshots.html) | `DELETE /sandboxes/{sandbox}/snapshots` |
| [Get the latest snapshot](api/getLatestSnapshot.html) | `GET /sandboxes/{sandbox}/snapshots/latest` |
| [Delete a snapshot](api/deleteSnapshot.html) | `DELETE /snapshots/{snapshot}` |
| [Browse a snapshot](api/getSnapshotTree.html) | `GET /snapshots/{snapshot}/tree` |
| [Download a file or folder from a snapshot](api/getSnapshotFile.html) | `GET /snapshots/{snapshot}/files` |
| [Get a signed archive URL](api/getSnapshotDownload.html) | `GET /snapshots/{snapshot}/download` |

## Templates

| Operation | Route |
|---|---|
| [List templates](api/listTemplates.html) | `GET /templates` |
| [Save a sandbox as a new template version](api/createTemplate.html) | `POST /templates` |
| [Get a template and its versions](api/getTemplate.html) | `GET /templates/{template}` |
| [Delete a template or a version](api/deleteTemplate.html) | `DELETE /templates/{template}` |
| [List share codes](api/listTemplateShares.html) | `GET /templates/{template}/shares` |
| [Create a share code](api/createTemplateShare.html) | `POST /templates/{template}/shares` |
| [Revoke a share code](api/revokeTemplateShare.html) | `DELETE /templates/{template}/shares/{share}` |

## Fleets

| Operation | Route |
|---|---|
| [List fleets](api/listFleets.html) | `GET /fleets` |
| [Create a fleet](api/createFleet.html) | `POST /fleets` |
| [Get a fleet](api/getFleet.html) | `GET /fleets/{fleet}` |
| [Change a fleet or scale it](api/updateFleet.html) | `PATCH /fleets/{fleet}` |
| [Delete a fleet and its sandboxes](api/deleteFleet.html) | `DELETE /fleets/{fleet}` |
| [Send one prompt to every member](api/promptFleet.html) | `POST /fleets/{fleet}/prompts` |
| [List wake timers and schedules](api/listSchedules.html) | `GET /schedules` |
| [Create a wake timer or schedule](api/createSchedule.html) | `POST /schedules` |
| [Delete a schedule](api/deleteSchedule.html) | `DELETE /schedules/{schedule}` |

## Billing

| Operation | Route |
|---|---|
| [Get the plan](api/getPlan.html) | `GET /billing/plan` |
| [Change the plan](api/setPlan.html) | `PUT /billing/plan` |
| [Get the wallet](api/getWallet.html) | `GET /billing/wallet` |
| [Quote a top-up with its bonus](api/quoteWallet.html) | `GET /billing/wallet/quote` |
| [Add money to the wallet](api/payWallet.html) | `POST /billing/wallet/payments` |
| [Set auto top-up](api/setAutoTopUp.html) | `PUT /billing/wallet/auto-top-up` |
| [Add a payment card](api/addCard.html) | `POST /billing/cards` |
| [List invoices](api/listInvoices.html) | `GET /billing/invoices` |
| [Get usage by project, fleet, label, member or size](api/getUsage.html) | `GET /usage` |
| [Export usage per sandbox, with labels, as CSV or JSON Lines](api/exportUsage.html) | `GET /usage/export` |
| [List budgets](api/listBudgets.html) | `GET /budgets` |
| [Create a hard or soft dollar budget](api/createBudget.html) | `POST /budgets` |
| [Change a budget](api/updateBudget.html) | `PATCH /budgets/{budget}` |
| [Delete a budget](api/deleteBudget.html) | `DELETE /budgets/{budget}` |
| [List reservations](api/listReservations.html) | `GET /reservations` |
| [Commit to capacity for one year](api/createReservation.html) | `POST /reservations` |

## Co-pilot

| Operation | Route |
|---|---|
| [Forecast this month](api/getForecast.html) | `GET /copilot/forecast` |
| [List savings recommendations with evidence](api/listRecommendations.html) | `GET /copilot/recommendations` |
| [Apply a recommendation](api/applyRecommendation.html) | `POST /copilot/recommendations/{recommendation}/apply` |