← All articles
Developers

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

  1. In the app open “Account & security → API access”.
  2. Choose a label, a permission (read only or read and write) and a lifetime, and confirm with your passphrase.
  3. 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" } }.

StatusCodeMeaning
400BAD_REQUESTInvalid request
401UNAUTHENTICATEDToken missing, invalid, expired or revoked
403FORBIDDENMissing permission (e.g. read-only token) or call reserved for the app
402PLAN_REQUIRED / QUOTA_EXCEEDEDPlan or storage insufficient
404NOT_FOUNDDoes not exist or no access
409VERSION_CONFLICTThe index changed in the meantime – reload and write again
409SLOTS_FULL / TEAM_LIMITNo free seat in the team, or too many teams for your plan
423TEAM_PAUSEDThe team is paused until the owner pays again
423CLOUD_LOCKED“My cloud” is locked until the data fits the plan again – deleting works
429RATE_LIMITEDToo 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

  1. POST /objects with the sizes of the encrypted pieces – the response contains presigned upload URLs.
  2. PUT each piece to its URL (format “frame2”, see cli/core.ts).
  3. POST /objects/{id}/complete.
  4. 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

CallDescription
GET /accountAccount overview: plan, storage, key envelopes (for the master key), passkeys, teams

Files (objects)

CallDescription
POST /objectsStart an upload: register pieces, response contains presigned upload URLs — { fmt: "frame2", teamId?: string | null, pieces: [{ index, cipherBytes }] }
POST /objects/{id}/urlsRefresh expired upload URLs for individual pieces — { pieces: number[] }
POST /objects/{id}/completeComplete an upload (verifies sizes, charges storage)
GET /objects/{id}/downloadPresigned download URLs for the encrypted pieces
DELETE /objects/{id}Delete an object permanently
POST /objects/{id}/trashMove to trash (paid plans)
POST /objects/{id}/restoreRestore from trash
POST /objects/{id}/versionKeep the current revision as a version (paid plans)
POST /objects/{id}/promotePromote an older version to current
POST /objects/{id}/moveMove a file: My Cloud ↔ team folder, team → team — { teamId: string | null }
GET /objects/{id}/proofFilecoin storage proof (certificate) of a file
GET /objects/trashObjects in the trash
GET /objects/versionsRetained versions
GET /objects/filecoinFilecoin status of all objects
POST /objects/statusWhich of these objects still exist (index reconciliation), at most 5000 IDs — { ids: string[] }

Encrypted index

CallDescription
GET /vault/indexRead the encrypted vault index (file names, keys, entries – ciphertext only)
PUT /vault/indexWrite the index (optimistic: baseVersion must match, otherwise 409) — { baseVersion: number, body: base64 }

Secure Send links

CallDescription
GET /sharesYour Secure Send links
POST /sharesCreate a link (encrypted metadata, expiry, download limit) — { objectId | objectIds, meta, expiresInHours, maxDownloads }
DELETE /shares/{id}Revoke a link

Shared vaults (incl. .env)

CallDescription
GET /vaultsShared vaults of a team (?team={id}), without a team your own: overview, own role, members, wrapped keys, encrypted index
POST /vaultsCreate a vault (in a team with role “edit”, without teamId as your own vault) — { id, wrapped, body, teamId? }
PUT /vaults/{id}/indexWrite the index (name, passwords, notes, 2FA, .env entries) – requires role “edit” — { baseVersion, body }
POST /vaults/{id}/keysDistribute keys to members / create a new generation – role “manage” — { generation, grants: [...], rotate? }
POST /vaults/{id}/membersAdd 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}/auditVault audit log – role “manage”
DELETE /vaults/{id}Delete the vault – role “manage”

Teams

CallDescription
GET /teamsYour teams (owned first, paged via ?cursor), plus limits and slots
POST /teamsCreate 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}/metaChange name and icon (encrypted) – role “admin” — { baseVersion, meta: base64 }
POST /teams/{id}/invitesCreate 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}/adminAdmin console: roles, policies, storage, slots – role “admin”
GET /teams/{id}/auditTeam audit log (?from, to, member, kind, limit)
GET /teams/{id}/reportCompliance report (?days)
PUT /teams/{id}/policySet team policies

Team folder

CallDescription
GET /teams/{id}/spaceState of the team folder: own role, key envelopes, members, index version
GET /teams/{id}/space/indexRead the encrypted folder index (version in the X-FV-Version header)
PUT /teams/{id}/space/indexWrite the folder index – role “edit” (binary body, base version in the X-FV-Base-Version header)
POST /teams/{id}/space/keysDistribute the folder key to members / create a new generation (role “edit”), at most 200 per call — { generation, grants: [{ accountId, wrapped }] }

Storage API (S3 access)

CallDescription
GET /s3Overview: access keys, buckets, endpoint
POST /s3/keysCreate an S3 access key (secret only in the response) — { label }
DELETE /s3/keys/{id}Revoke an S3 access key
POST /s3/bucketsCreate a bucket (optionally with Object Lock) — { name, objectLock }
PATCH /s3/buckets/{name}Change retention and lock of a bucket

Misc

CallDescription
GET /healthService health (no auth)
GET /statusPublic status and incidents (no auth)
GET /fxExchange rates for price display
GET /openapi.jsonThis API as an OpenAPI 3.1 document
Didn’t find what you need? Contact support →