REST API

List your vaults over plain HTTPS - one read-only endpoint, using the same OAuth token your MCP clients already use. No SDK, no API key.

The endpoint

text

GET https://api.agentage.io/v1/vaults

One endpoint, read-only. Reading and writing notes stays on the MCP server - this API only tells you which vaults your token can see.

Authentication

Send an OAuth 2.1 access token as a bearer header:

text

Authorization: Bearer <access-token>

The token is the same one issued when you connect any MCP client (OAuth 2.1 with PKCE, sign-in at auth.agentage.io). Which vaults you see is decided by the token, not by request parameters - a token scoped to one vault lists only that vault.

Example

bash

curl -s \
  -H "Authorization: Bearer $AGENTAGE_TOKEN" \
  https://api.agentage.io/v1/vaults

json

{
  "vaults": [
    {
      "name": "default",
      "files": 412,
      "folders": 37,
      "updated": "2026-07-06T07:31:02+00:00",
      "empty": false
    },
    {
      "name": "work",
      "files": 128,
      "folders": 12,
      "updated": "2026-07-05T21:47:55+00:00",
      "empty": false
    }
  ]
}

Response schema

Field	Type	Meaning
`vaults`	array	Vaults visible to the presented token, one object per vault.
`vaults[].name`	string	Vault slug, 1-64 chars of `a-z 0-9 _ -`.
`vaults[].files`	integer	Number of notes currently in the vault.
`vaults[].folders`	integer	Number of folders in the vault.
`vaults[].updated`	string (ISO 8601) or null	Last write to the vault; `null` when the vault has no content yet.
`vaults[].empty`	boolean	True when the vault has no notes.

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["vaults"],
  "properties": {
    "vaults": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "files", "folders", "updated", "empty"],
        "properties": {
          "name": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" },
          "files": { "type": "integer", "minimum": 0 },
          "folders": { "type": "integer", "minimum": 0 },
          "updated": { "type": ["string", "null"], "format": "date-time" },
          "empty": { "type": "boolean" }
        }
      }
    }
  }
}

Errors

Status	Meaning	What to do
`401`	Missing, expired, or invalid token.	Re-authenticate and retry with a fresh token.
`429`	Rate limit exceeded.	Back off and retry after the window resets.
`503`	Auth service temporarily unavailable (never means a bad token).	Retry with backoff.

Limits and versioning

Read-only: this API never modifies a vault.
Rate limited to 60 requests per minute per IP.
The /v1 contract is frozen: fields are only ever added, never renamed or removed. Breaking changes would ship as /v2.

What this API is not

Not a way to read or write notes - use the MCP server (memory__search/read/write/edit/list/delete).
Not a sync channel - vault contents sync over git (Obsidian plugin, CLI).
No API keys - OAuth 2.1 bearer only.