Docs

API

Personal API keys let external tools (scripts, CI pipelines, an MCP server, etc.) call the Velstash API on your behalf, without sharing your dashboard login. Instead, API calls are authenticated via a plain bearer-token API.

Getting a key

Log into the dashboard and go to API Keys.
Click Create new key, give it a label, and select the scopes it needs.
Copy the key when shown. Please note the key is displayed exactly once and cannot be retrieved again. If you lose it, revoke it and create a new one.

Keys look like vlst_<64 hex characters>.

Authentication

Send the key as a bearer token:

curl -H "Authorization: Bearer vlst_..." \
  https://app.velstash.io/api/v1/cache/instances

Missing, malformed, or revoked keys get:

HTTP 401
{"error": "invalid_token", "message": "..."}

Scopes

Each key is granted one or more scopes when it's created. An endpoint checks for the specific scope(s) it needs; a key without the required scope gets:

HTTP 403
{"error": "insufficient_scope", "message": "..."}

Available scopes:

Scope	Grants
`instances:read`	Read instance data
`credentials:read`	Read credential metadata (not secrets)
`credentials:write`	Create/revoke credentials
`billing:read`	Read billing/usage data

Creating/deleting instances, changing your plan, and changing your payment method are never available through the API, regardless of scopes — those actions can only be done through the web dashboard.

Rate limiting

Each key is limited to 60 requests per minute. Going over returns:

HTTP 429
{"error": "rate_limited", "message": "..."}

Response format

Successful responses wrap their payload in a data key:

{"data": {"id": "...", "name": "...", "...": "..."}}

or, for a list:

{"data": [{"...": "..."}, {"...": "..."}]}

Errors always look like:

{"error": "<error_code>", "message": "<human-readable description>"}

Endpoints

GET /api/v1/cache/instances

Scope: instances:read

List your instances across all regions.

{
  "data": [
    {
      "id": "f1230fcb-1780-46ff-a097-849cbf68c5c6",
      "name": "My instance",
      "region_id": "mc1-hel1-hetzner",
      "status": "running",
      "memory_mb": 2048,
      "created_at": "2026-09-14T15:44:57+00:00"
    }
  ]
}

GET /api/v1/cache/instances/{instanceId}

Scope: instances:read

Get a single instance you own. Returns 404 if the instance doesn't exist or isn't yours (the same response either way, so ownership isn't leaked).

{
  "data": {
    "id": "f1230fcb-1780-46ff-a097-849cbf68c5c6",
    "name": "My instance",
    "region_id": "mc1-hel1-hetzner",
    "status": "running",
    "memory_mb": 2048,
    "created_at": "2026-09-14T15:44:57+00:00"
  }
}

Not yet available

credentials:read, credentials:write, and billing:read scopes exist and can be granted to a key today, but there are no endpoints behind them yet — only the instances endpoints above are live.