← All articlesDevelopers
REST API for integrations
Use the whole app via API: tokens, limits, errors and all endpoints.
Everything the web app can do is also available through the REST API – for your own programs, scripts and integrations. The API runs on the same platform as the app and is reachable at api.everhold.io (base URL https://api.everhold.io/v1). The S3 gateway (storage API) has its own hostname: s3.everhold.io.
Zero-knowledge applies here too: the API returns and accepts ciphertext only. Encryption and decryption happen in your program with your account master key (passphrase → Argon2id → key envelope from GET /account). A token never exposes plaintext. The backup tool (cli/everhold.ts) is the reference implementation – it uses exactly this API.
Create a token
- In the app open “Account & security → API access”.
- Choose a label, a permission (read only or read and write) and a lifetime, and confirm with your passphrase.
- Copy the token – it is shown only once. Only a hash is stored.
curl https://api.everhold.io/v1/account \
-H "Authorization: Bearer evh_…"
Limits
Every token has its own per-minute limit: Free 60, Pro 300, Team 1200 requests. In addition each IP address is capped at 600 read and 120 write requests per minute. Sign-in, registration and recovery are limited even more tightly. When exceeded the API answers 429 with a Retry-After header (seconds) and the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers.
Errors
Errors are JSON: { "error": { "code", "message", "details" } }.
| Status | Code | Meaning |
|---|
| 400 | BAD_REQUEST | Invalid request |
| 401 | UNAUTHENTICATED | Token missing, invalid, expired or revoked |
| 403 | FORBIDDEN | Missing permission (e.g. read-only token) or call reserved for the app |
| 402 | PLAN_REQUIRED / QUOTA_EXCEEDED | Plan or storage insufficient |
| 404 | NOT_FOUND | Does not exist or no access |
| 409 | VERSION_CONFLICT | The index changed in the meantime – reload and write again |
| 409 | SLOTS_FULL / TEAM_LIMIT | No free seat in the team, or too many teams for your plan |
| 423 | TEAM_PAUSED | The team is paused until the owner pays again |
| 423 | CLOUD_LOCKED | “My cloud” is locked until the data fits the plan again – deleting works |
| 429 | RATE_LIMITED | Too many requests – retry after Retry-After |
App only
For security reasons not possible with a token: sign-in and registration, passphrase, passkeys, recovery kit and sessions, token management, billing, seats and credit, admin, joining, taking over and deleting teams, SSO, company emergency access and deleting the account.
Uploading and downloading files
- POST /objects with the sizes of the encrypted pieces – the response contains presigned upload URLs.
- PUT each piece to its URL (format “frame2”, see cli/core.ts).
- POST /objects/{id}/complete.
- Write file name, file key (wrapped with the master key) and piece metadata to the encrypted index: PUT /vault/index with baseVersion.
.env files in shared vaults
Inside the encrypted index of a shared vault, .env files are entries of type “env”: { kind: "env", title: <project>, environment: "production" | "preview" | …, vars: [{ key, value }] }. This lets you read and write environment variables from CI/CD (GET /vaults, PUT /vaults/{id}/index) – encrypted with the vault key your account receives through its ECDH envelope.
OpenAPI
Machine-readable description: https://api.everhold.io/v1/openapi.json (OpenAPI 3.1) – importable into Postman, Insomnia or client library generators.
Endpoints
Account
| Call | Description |
|---|
| GET /account | Account overview: plan, storage, key envelopes (for the master key), passkeys, teams |
Files (objects)
| Call | Description |
|---|
| POST /objects | Start an upload: register pieces, response contains presigned upload URLs — { fmt: "frame2", teamId?: string | null, pieces: [{ index, cipherBytes }] } |
| POST /objects/{id}/urls | Refresh expired upload URLs for individual pieces — { pieces: number[] } |
| POST /objects/{id}/complete | Complete an upload (verifies sizes, charges storage) |
| GET /objects/{id}/download | Presigned download URLs for the encrypted pieces |
| DELETE /objects/{id} | Delete an object permanently |
| POST /objects/{id}/trash | Move to trash (paid plans) |
| POST /objects/{id}/restore | Restore from trash |
| POST /objects/{id}/version | Keep the current revision as a version (paid plans) |
| POST /objects/{id}/promote | Promote an older version to current |
| POST /objects/{id}/move | Move a file: My Cloud ↔ team folder, team → team — { teamId: string | null } |
| GET /objects/{id}/proof | Filecoin storage proof (certificate) of a file |
| GET /objects/trash | Objects in the trash |
| GET /objects/versions | Retained versions |
| GET /objects/filecoin | Filecoin status of all objects |
| POST /objects/status | Which of these objects still exist (index reconciliation), at most 5000 IDs — { ids: string[] } |
Encrypted index
| Call | Description |
|---|
| GET /vault/index | Read the encrypted vault index (file names, keys, entries – ciphertext only) |
| PUT /vault/index | Write the index (optimistic: baseVersion must match, otherwise 409) — { baseVersion: number, body: base64 } |
Secure Send links
| Call | Description |
|---|
| GET /shares | Your Secure Send links |
| POST /shares | Create a link (encrypted metadata, expiry, download limit) — { objectId | objectIds, meta, expiresInHours, maxDownloads } |
| DELETE /shares/{id} | Revoke a link |
Shared vaults (incl. .env)
| Call | Description |
|---|
| GET /vaults | Shared vaults of a team (?team={id}), without a team your own: overview, own role, members, wrapped keys, encrypted index |
| POST /vaults | Create a vault (in a team with role “edit”, without teamId as your own vault) — { id, wrapped, body, teamId? } |
| PUT /vaults/{id}/index | Write the index (name, passwords, notes, 2FA, .env entries) – requires role “edit” — { baseVersion, body } |
| POST /vaults/{id}/keys | Distribute keys to members / create a new generation – role “manage” — { generation, grants: [...], rotate? } |
| POST /vaults/{id}/members | Add a person — { accountId, role: "view" | "edit" | "manage" } |
| PATCH /vaults/{id}/members/{member} | Change a role — { role } |
| DELETE /vaults/{id}/members/{member} | Remove a person or leave the vault |
| GET /vaults/{id}/audit | Vault audit log – role “manage” |
| DELETE /vaults/{id} | Delete the vault – role “manage” |
Teams
| Call | Description |
|---|
| GET /teams | Your teams (owned first, paged via ?cursor), plus limits and slots |
| POST /teams | Create a team (own Team or Enterprise plan): the client generates the ID, the wrapped first folder key and the encrypted meta (name, icon) — { id, wrapped, meta: base64 } |
| GET /teams/{id} | Team: members with role and slot, policy; from role “admin” also invitations and slots |
| PUT /teams/{id}/meta | Change name and icon (encrypted) – role “admin” — { baseVersion, meta: base64 } |
| POST /teams/{id}/invites | Create an invitation link – role “admin” (only the owner invites admins) — { role?: "view" | "edit" | "admin" } |
| DELETE /teams/{id}/invites/{inviteId} | Withdraw an invitation |
| PATCH /teams/{id}/members/{accountId} | Change a role – role “admin” (only the owner grants admin) — { role: "view" | "edit" | "admin" } |
| DELETE /teams/{id}/members/{accountId} | Remove a member or leave the team (your own ID) |
| GET /teams/{id}/admin | Admin console: roles, policies, storage, slots – role “admin” |
| GET /teams/{id}/audit | Team audit log (?from, to, member, kind, limit) |
| GET /teams/{id}/report | Compliance report (?days) |
| PUT /teams/{id}/policy | Set team policies |
Team folder
| Call | Description |
|---|
| GET /teams/{id}/space | State of the team folder: own role, key envelopes, members, index version |
| GET /teams/{id}/space/index | Read the encrypted folder index (version in the X-FV-Version header) |
| PUT /teams/{id}/space/index | Write the folder index – role “edit” (binary body, base version in the X-FV-Base-Version header) |
| POST /teams/{id}/space/keys | Distribute the folder key to members / create a new generation (role “edit”), at most 200 per call — { generation, grants: [{ accountId, wrapped }] } |
Storage API (S3 access)
| Call | Description |
|---|
| GET /s3 | Overview: access keys, buckets, endpoint |
| POST /s3/keys | Create an S3 access key (secret only in the response) — { label } |
| DELETE /s3/keys/{id} | Revoke an S3 access key |
| POST /s3/buckets | Create a bucket (optionally with Object Lock) — { name, objectLock } |
| PATCH /s3/buckets/{name} | Change retention and lock of a bucket |
Misc
| Call | Description |
|---|
| GET /health | Service health (no auth) |
| GET /status | Public status and incidents (no auth) |
| GET /fx | Exchange rates for price display |
| GET /openapi.json | This API as an OpenAPI 3.1 document |