Skip to main content
POST
Create world

Authorizations

Authorization
string
header
required

Worlds API data-plane token.

Body

application/json
displayName
string

User-facing display name for the new world.

embeddingModel
enum<string>

Embedding model to use for vector search, as provider/model. Allowlist: openai/text-embedding-3-small (recommended), openai/text-embedding-3-large (pinned to 1536 dimensions), legacy openai/text-embedding-ada-002, and the same OpenAI models through OpenRouter as openrouter/openai/text-embedding-3-small and openrouter/openai/text-embedding-3-large. The model's provider decides which namespace credential is used. Defaults to the platform default, which reports embeddingStatus unconfigured until a model is chosen.

Available options:
openai/text-embedding-3-small,
openai/text-embedding-3-large,
openai/text-embedding-ada-002,
openrouter/openai/text-embedding-3-small,
openrouter/openai/text-embedding-3-large
chunkSize
integer

Maximum quads per chunk for vector search indexing. Defaults to the platform default.

Required range: x > 0
topK
integer

Default number of top results for search queries against this world.

Required range: x > 0
minScore
number

Default minimum relevance score (0–1) for search results in this world.

Required range: 0 <= x <= 1
inference
object

Opt the world in to OWL 2 RL inference. Off when omitted. The data plane additionally needs the quads.derived column before enabling.

Response

Created World

id
string
required

Immutable World ID minted by Worlds API as w_<ULID>.

Pattern: ^w_[0-7][0-9a-hjkmnp-tv-z]{25}$
displayName
string
required

User-facing display name for the world. Set on creation or update.

state
string
required

Lifecycle state: active, deleted, or suspended. Deleted worlds enter a 30-day grace period before permanent purge.

storage
enum<string>
required

Storage backend for the world. All worlds share a single Cloudflare D1 database, separated by world_id.

Available options:
d1
embeddingModel
string
required

Embedding model identifier used for vector search indexing, e.g. openai/text-embedding-3-small or openrouter/openai/text-embedding-3-small. Values outside the allowlist (including the legacy tfjs-universal-sentence-encoder default) are reported as embeddingStatus unconfigured and search stays keyword-only.

embeddingStatus
enum<string>
required

Whether vector search is usable for this world. unconfigured: embeddings are not enabled or the model is not allowlisted. no_credential: the namespace has no active embedding credential for the provider of this world's model. invalid: the provider rejected the namespace credential. stale: vectors are not built for the current model; search is keyword-only until POST /worlds/{worldId}/reindex. partial: some vectors failed to sync; hybrid search covers what exists. ready: vectors are current.

Available options:
unconfigured,
no_credential,
invalid,
stale,
partial,
ready
chunkSize
integer
required

Maximum number of RDF quads per chunk when indexing for vector search.

topK
integer
required

Default number of top search results to return when the caller does not override.

minScore
number
required

Default minimum relevance score (0–1) for search results. Results below this threshold are omitted.

createTime
string
required

ISO 8601 timestamp when the world was created.

updateTime
string
required

ISO 8601 timestamp when the world was last updated.

inference
object

OWL 2 RL inference setting. Omitted when never configured, which means inference is off.

deleteTime
string

ISO 8601 timestamp when the world was soft-deleted. Null if not deleted.

expireTime
string

ISO 8601 timestamp when the world will be permanently purged after the grace period. Null if not scheduled for purge.