Agent Quickstart
Provision a ZeroDB project, connect, and perform a real read/write — written for an autonomous AI agent integrating with no human in the loop. Every endpoint, field, and status code below was confirmed against the live production API while writing this page. For the single-command CLI path, see Quick Start; for OAuth/scoped-delegation auth, see Agent Authentication.
Consent rule — read this first
Provisioning requires agree_terms: true in the request body. An agent must never send this on behalf of a user without the user's real, explicit authorization — this is not a formality the agent can satisfy on its own. If you are acting for a human, confirm their agreement first; if you are a human running this yourself, you are agreeing for your own account.
Discover
What ZeroDB is, machine-readable.
ZeroDB is the agentic database — vector search, agent memory, NoSQL tables, event streaming, file storage, embeddings, and managed PostgreSQL behind one API. A plain-text, agent-oriented entry point is published at:
- zerodb.ainative.studio/llms.txt — when to use ZeroDB, when not to, core capabilities, and links onward
- zerodb.ainative.studio/llms-full.txt — the comprehensive single-file reference (API, auth, every SDK quickstart)
Provision a database
No signup, no email, no password. Confirmed live: POST /api/v1/public/instant-db with no body returns HTTP 451 (terms not agreed), proving the endpoint and its consent check are real and enforced.
curl -X POST https://api.ainative.studio/api/v1/public/instant-db \
-H "Content-Type: application/json" \
-d '{"agree_terms": true}'Optional request fields: on_behalf_of — a user identifier to record who the agent is acting for, for the terms-acceptance audit record; email — capture it here and the claim-reminder email is sent automatically, so an agent that never surfaces the claim_url to a human itself still gets the project claimed before the 72-hour window closes.
Extract credentials
Response fields, read directly from the provisioning handler's source.
{
"api_key": "tmp_...",
"project_id": "<uuid>",
"base_url": "https://api.ainative.studio",
"expires_at": "<ISO 8601 timestamp, 72h from creation>",
"claim_url": "https://www.ainative.studio/claim?token=...&project=...",
"connection_string": "<direct Postgres URL, if applicable>",
"mcp": {
"memory_server": "npx ainative-zerodb-memory-mcp",
"full_server": "npx ainative-zerodb-mcp-server",
"discovery_url": "https://api.ainative.studio/.well-known/mcp.json",
"env_vars": { "ZERODB_API_KEY": "...", "ZERODB_PROJECT_ID": "..." }
},
"limits": {
"vectors": 10000,
"memory_records": 1000,
"storage_mb": 50,
"embeddings_per_month": 1000,
"chat_credits": 50
},
"warning": "This is a temporary free-tier key..."
}The api_key is tmp_-prefixed — distinct from the sk_-prefixed key a registered, paid account holds. Store api_key and project_id; without them the project is unreachable once this response is gone.
Connect and perform a first operation
Confirmed live: both endpoints below return 401 AUTH_REQUIRED with no key (route exists, auth is checked), not 404.
Write — store a memory
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/remember \
-H "X-API-Key: <api_key>" \
-H "Content-Type: application/json" \
-d '{"content": "Hello ZeroDB"}'Read — recall by meaning
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/recall \
-H "X-API-Key: <api_key>" \
-H "Content-Type: application/json" \
-d '{"query": "Hello"}'Prefer an SDK over raw HTTP? Real, published packages exist for Python, React, and Next.js.
Connect via MCP
For an agent that is itself an MCP client (Claude Code, Cursor, etc.) rather than calling the REST API directly.
Fast path — one command, non-interactive
npx zerodb-cli init --yes
--yes (zerodb-cli ≥0.1.4) explicitly agrees to the Terms of Service on the operator's own authority — required for non-interactive use, since the CLI will not silently assume consent. Without --yes and without a terminal attached, it fails fast with an error rather than hanging. Provisions a project, writes .env, and auto-configures your editor's MCP file. Full walkthrough: MCP Server Setup.
Manual — real discovery manifest
The live manifest at https://api.ainative.studio/.well-known/mcp.json lists both ZeroDB-specific MCP servers with install commands and connection details:
{
"name": "zerodb-memory",
"install_stdio": "npx ainative-zerodb-memory-mcp",
"capabilities": ["memory", "semantic-search", "context-management"]
}
{
"name": "zerodb-full",
"install_stdio": "npx ainative-zerodb-mcp-server",
"capabilities": ["vector-search", "nosql", "file-storage", "events", "postgres", "memory", "embeddings", "quantum"]
}zerodb-memory ships 18 tools (4 plan + 5 write-back + 9 memory/search); zerodb-full ships 97 tools. Both counted directly from each package's real published source (ainative-zerodb-memory-mcp@1.2.12 and ainative-zerodb-mcp-server@2.5.2, the actual current latest versions) — not read from any README or manifest, which currently state other, stale numbers for both. Trust the tool list an MCP client gets back from a real tools/list call over any documented count, including this one.
Manual client config (e.g. .mcp.json for Claude Code):
{
"mcpServers": {
"zerodb-memory": {
"command": "npx",
"args": ["ainative-zerodb-memory-mcp"],
"env": { "ZERODB_API_KEY": "<api_key>" }
}
}
}Claim the project before it expires
Confirmed live: calling claim with an empty body returns 422 naming exactly the required fields — token and project_id — not 404.
curl -X POST https://api.ainative.studio/api/v1/public/instant-db/claim \
-H "Content-Type: application/json" \
-d '{"token": "<token_from_claim_url>", "project_id": "<project_id>"}'The token and project_id are parsed out of the claim_url query string returned at provisioning time. No bearer token is required to call this — the claim token itself proves ownership. Confirmed directly from the handler's own source: authentication is optional here. If the caller isn't logged in yet, the response is {"claimed": false, "login_url": "..."} — hand that URL to the human to finish signing in and completing the claim. Call the same endpoint again once they're authenticated (e.g. with their session cookie or bearer token) to get back {"claimed": true, "api_key": "sk_..."}.
If it is not claimed within 72 hours, the trial key and its data are deleted — the project is not recoverable after expiry.
Error recovery
| Status | Meaning | Fix |
|---|---|---|
451 | terms_required — agree_terms was missing or false | Re-send with agree_terms: true, only after real authorization (see the consent rule above) |
429 | 5 instant databases already created from this IP today (unauthenticated requests only) | Get an authenticated key instead at /pricing, then pass it directly: npx zerodb-cli init --api-key <key> |
401 | AUTH_REQUIRED — missing or invalid X-API-Key | Check the header name and that the key wasn't truncated when stored |
422 | Request body missing a required field — the error body names exactly which | Read detail[].loc in the response; it points at the exact missing field |
Capability summary
What a provisioned trial project can do, from the real limits block above.
- Vector search — up to 10,000 vectors on a trial project
- Agent memory (store / recall / forget) — up to 1,000 memory records
- Embeddings generation — up to 1,000 per month
- Storage — 50 MB
- Chat completions — 50 credits (limited; register for full access)
- NoSQL tables, event streaming, file storage, dedicated PostgreSQL — available on a claimed/registered project
These are trial-tier limits on an unclaimed instant-db project, not the limits of the platform as a whole — see /pricing for registered-account tiers.