Skip to content
vvd
Start building
Platform API— browse docs
On this page

Quickstart

Create an API key and make your first calls in two minutes.

1. Get an API key

Sign in at vvd.world, open Settings → API keys, and create a key. Copy it — it's shown only once. Keys look like vvd_live_….

Note:

A key acts as your account and never expires. Revoke it any time from the same page to disconnect whatever is using it.

2. Call the API

Every request carries the key as a bearer token.

export VVD_KEY=vvd_live_your_key_here

# Who am I?
curl https://vvd.world/api/v1/me \
  -H "Authorization: Bearer $VVD_KEY"

# List my worlds
curl https://vvd.world/api/v1/worlds \
  -H "Authorization: Bearer $VVD_KEY"

3. Create a world and a document

# Create a world
curl -X POST https://vvd.world/api/v1/worlds \
  -H "Authorization: Bearer $VVD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Eldermoor", "genre": "fantasy"}'
# → { "id": "…", "slug": "…", "name": "Eldermoor" }

# Add a character card to it
curl -X POST https://vvd.world/api/v1/worlds/WORLD_ID/documents \
  -H "Authorization: Bearer $VVD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sir Reginald", "documentType": "card"}'
Note:

Reading and editing world content over the API needs the world to be on the Pro or Studio plan. Building tools and apps with the CLI is free on every plan.

4. Or skip the key — connect over MCP

An MCP client that supports OAuth doesn't need a key at all: add https://vvd.world/api/mcp as a connector, approve the connection in your browser, and it can work with your worlds. See MCP server.

Next

ConceptsWorlds, documents, eras, projects.AuthenticationKeys, sessions, and OAuth.API referenceEvery endpoint.