HTTP API Reference

HTTP/WebSocket API for the mooR virtual-world server.

Content negotiation — Most /v1/* endpoints support two response formats selected via the Accept header:

If neither is acceptable, the server returns 406 Not Acceptable.

Authentication — Authenticated endpoints require an X-Moor-Auth-Token header containing a PASETO v4.public token obtained from /auth/connect or /auth/create. Some endpoints also require X-Moor-Client-Token and X-Moor-Client-Id headers for session continuity.

FlatBuffers note — FlatBuffer request/response bodies are opaque binary blobs whose schemas are defined in the moor-schema crate. This spec documents their logical content in prose; the wire format is governed by the .fbs files, not JSON Schema.

Auth

Password-based authentication (login / validate / logout)

POST /auth/connect

Authenticate an existing player

Runs the connect login command against the daemon. On success the response body is a FlatBuffer LoginResult and the three session headers are set.

Request body (required)

• Content-Type: application/x-www-form-urlencoded

  Field	Type	Required	Description
  player	string	Yes	Player name
  password	string	Yes	Player password

Responses

• 200: Login successful
  • Header X-Moor-Auth-Token: PASETO auth token for subsequent requests
  • Header X-Moor-Client-Token: Session token for this connection
  • Header X-Moor-Client-Id: Unique ID for this client session
  • Content-Type: application/x-flatbuffers
• 401: Missing or invalid auth token
• 403: Login rejected by daemon
• 500: Internal server error
• 502: Malformed response from daemon
• 503: Daemon is unreachable

POST /auth/create

Create a new player account

Runs the create login command against the daemon. Identical to /auth/connect except the daemon verb is :do_login_command("create", …).

Request body (required)

• Content-Type: application/x-www-form-urlencoded

  Field	Type	Required	Description
  player	string	Yes	Player name
  password	string	Yes	Player password

Responses

• 200: Account created and logged in
  • Header X-Moor-Auth-Token
  • Header X-Moor-Client-Token
  • Header X-Moor-Client-Id
  • Content-Type: application/x-flatbuffers
• 401: Missing or invalid auth token
• 403: Account creation rejected by daemon
• 500: Internal server error
• 502: Malformed response from daemon
• 503: Daemon is unreachable

GET /auth/validate

Validate an auth token

Round-trips to the daemon to verify the token is still valid. An ephemeral attach/detach is performed; the connection is cleaned up automatically.

Requires: X-Moor-Auth-Token

Responses

• 200: Token is valid (empty body)
• 401: Missing or invalid auth token
• 503: Daemon is unreachable

POST /auth/logout

Explicitly log out a player session

Sends a detach message to the daemon with disconnected=true, triggering user_disconnected. Requires both the auth token and client credentials.

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Logout successful (empty body)
• 401: Missing or invalid auth token
• 500: Internal server error

OAuth2

OAuth2 federated authentication. These routes are only registered when OAuth2 is enabled in the server configuration; otherwise they return 404.

GET /v1/oauth2/config

Get OAuth2 configuration

Returns whether OAuth2 is enabled and the list of configured providers. Route is only present when OAuth2 is enabled.

Responses

• 200: OAuth2 configuration
  • Content-Type: application/json
• 404: OAuth2 not enabled (route absent)

GET /auth/oauth2/{provider}/authorize

Start a cookie-bound OAuth2 authorization flow

Generates a provider authorization URL and a CSRF state token. Sets a moor_oauth_nonce cookie for cookie-bound redemption.

Parameters

Responses

• 200: Authorization URL generated
  • Header Set-Cookie: moor_oauth_nonce HttpOnly cookie
  • Content-Type: application/json
• 400: Unknown provider
  • Content-Type: application/json
• 404: OAuth2 not enabled

POST /auth/oauth2/{provider}/app/start

Start a proof-bound OAuth2 authorization flow

Starts OAuth2 for clients that do not rely on browser cookies. Stores redirect target + PKCE challenge server-side and returns an authorization URL. Callback redirects to the app redirect URI with a one-time handoff_code.

Parameters

Request body (required)

• Content-Type: application/json

  Field	Type	Required	Description
  redirect_uri	string	Yes	Redirect target for proof-bound callback handoff
  intent	string	No	Optional client-defined intent/context
  code_challenge	string	Yes	PKCE code challenge (S256)
  code_challenge_method	S256	Yes

Responses

• 200: Authorization URL generated
  • Content-Type: application/json
• 400: Invalid provider, redirect URI, or PKCE input
  • Content-Type: application/json
• 404: OAuth2 not enabled

GET /auth/oauth2/{provider}/callback

OAuth2 provider callback

Called by the OAuth2 provider after user consent. Validates the CSRF state, exchanges the authorization code for user info, and redirects according to flow binding:

• Cookie-bound existing user → /#auth_code={code}
• Cookie-bound new user → /#oauth2_code={code}&oauth2_display={json}
• Proof-bound → {redirect_uri}?handoff_code={code}

The code is a server-side one-time token redeemable via /auth/oauth2/exchange (cookie) or /auth/oauth2/app/exchange (proof).

Parameters

Responses

• 302: Redirect to client with one-time code in fragment
• 404: OAuth2 not enabled (route absent)

POST /auth/oauth2/exchange

Exchange a cookie-bound one-time code for tokens or identity

Redeems a server-side one-time code produced by the callback. Returns either an auth_session (existing user) or an identity (new user needing account choice). Requires the moor_oauth_nonce cookie.

Request body (required)

• Content-Type: application/json

  Field	Type	Required	Description
  code	string	Yes	One-time server-side code from callback redirect

Responses

• 200: Code exchanged
  • Content-Type: application/json
• 401: Invalid/expired code or missing nonce cookie
  • Content-Type: application/json
• 404: OAuth2 not enabled (route absent)

POST /auth/oauth2/app/exchange

Exchange a proof-bound handoff code

Redeems a one-time proof-bound handoff code using a PKCE verifier. Returns an auth session for existing users, or identity details plus an identity_code for account-choice submission.

Request body (required)

• Content-Type: application/json

  Field	Type	Required	Description
  handoff_code	string	Yes	One-time handoff code from callback redirect
  code_verifier	string	Yes	PKCE verifier matching the start request challenge

Responses

• 200: Code exchanged
  • Content-Type: application/json
• 401: Invalid/expired code or invalid verifier
  • Content-Type: application/json
• 404: OAuth2 not enabled (route absent)

POST /auth/oauth2/account

Create or link an account after OAuth2

Submits the user's account-choice decision (create new player or link to existing player). The oauth2_code must resolve to a verified Identity on the server side. Requires moor_oauth_nonce cookie.

Request body (required)

• Content-Type: application/json

  Field	Type	Required	Description
  mode	oauth2_create | oauth2_connect	Yes
  oauth2_code	string	Yes	One-time code from callback redirect
  player_name	string	No	Desired player name (for oauth2_create)
  existing_email	string	No	Email of existing account to link (for oauth2_connect)
  existing_password	string	No	Password of existing account (for oauth2_connect)

Responses

• 200: Account created/linked, session established
  • Content-Type: application/json
• 400: Invalid mode or code type mismatch
  • Content-Type: application/json
• 401: Authentication failed or invalid code
  • Content-Type: application/json
• 404: OAuth2 not enabled
• 500: Internal server error

POST /auth/oauth2/app/account

Create or link account using proof-bound identity code

Submits account-choice for proof-bound OAuth2 flows. Requires identity_code and PKCE code_verifier; no nonce cookie.

Request body (required)

• Content-Type: application/json

  Field	Type	Required	Description
  mode	oauth2_create | oauth2_connect	Yes
  identity_code	string	Yes	One-time identity code from /auth/oauth2/app/exchange
  code_verifier	string	Yes	PKCE verifier used to bind account-choice redemption
  player_name	string	No	Desired player name (for oauth2_create)
  existing_email	string	No	Email of existing account to link (for oauth2_connect)
  existing_password	string	No	Password of existing account (for oauth2_connect)

Responses

• 200: Account created/linked, session established
  • Content-Type: application/json
• 400: Invalid mode or code type mismatch
  • Content-Type: application/json
• 401: Authentication failed or invalid code
  • Content-Type: application/json
• 404: OAuth2 not enabled
• 500: Internal server error

WebSocket

WebSocket connections for real-time interaction

GET /ws/attach/connect

WebSocket upgrade — attach with existing player

Upgrades to a WebSocket connection for an already-authenticated player (the connect login path).

Auth credentials can be passed as HTTP headers or via Sec-WebSocket-Protocol subprotocols:

The server selects moor as the WebSocket subprotocol.

Note: Full WebSocket message framing is FlatBuffer-based and is outside the scope of this HTTP spec.

Requires: X-Moor-Auth-Token

Responses

• 101: WebSocket upgrade successful
• 401: Missing or invalid auth token
• 500: Internal server error

GET /ws/attach/create

WebSocket upgrade — attach with new player

Same as /ws/attach/connect but used when the player was created via /auth/create. See that endpoint for auth details.

Requires: X-Moor-Auth-Token

Responses

• 101: WebSocket upgrade successful
• 401: Missing or invalid auth token
• 500: Internal server error

Commands

MOO command execution

POST /v1/command

Execute a MOO command and return its result

The daemon parses and executes one MOO command as the authenticated player. The request does not create a persistent connection. Input requests fail. Output from forked tasks is not included.

The daemon processes the command in this order:

1. If #0:do_command exists, the daemon calls it first.
2. If #0:do_command returns a true value, the task succeeds with that value.
3. If the verb is absent or returns false, the daemon uses the normal command parser.
4. If the parser rejects the input, the outcome is InvocationError with CommandExecutionError(CouldNotParseCommand).
5. If no command verb matches and the player has a location, the daemon calls :huh there.
6. If the player has no location or :huh does not exist, the outcome is InvocationError with CommandExecutionError(NoCommandMatch).

Any invoked verb can return a value or raise an error. This includes #0:do_command, the selected command verb, and :huh. The result becomes the invocation outcome. The protocol does not create an "I do not understand" message. If :huh creates this message, it is ordinary narrative output.

Permission and database errors use the corresponding CommandExecutionError variant. Deadline, cancellation, and verb execution errors use their normal scheduler-error variants. All these task errors appear inside InvocationError.

A valid HTTP request receives status 200 after the task finishes. HTTP status 200 does not mean that the MOO task succeeded. The InvocationResponse.outcome field identifies InvocationSuccess or InvocationError. Task errors remain inside InvocationError. The output field contains committed root-task output for both outcomes. It can contain output committed before a later task error.

HTTP status 400 means that the HTTP request is invalid. This includes an invalid timeout or a body that is not valid UTF-8. A MOO parse error is a completed task response with HTTP status 200.

Requires: X-Moor-Auth-Token

Parameters

Request body (required)

• Content-Type: text/plain

  Example:

  look
  

Responses

• 200: Completed command invocation. InvocationResponse.outcome identifies task success or error. The HTTP status remains 200 for a completed InvocationError response.
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid timeout, or the request body is not valid UTF-8
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 415: Unsupported Content-Type
• 500: Internal server error
• 503: Daemon is unreachable

Eval

Server-side MOO expression evaluation

POST /v1/eval

Evaluate a MOO expression

The daemon evaluates a MOO expression as the authenticated player. The request creates no daemon connection. The response contains the result or error and committed root-task output.

Requires: X-Moor-Auth-Token

Parameters

Request body (required)

• Content-Type: text/plain

  Example:

  player:name()
  

Responses

• 200: Evaluation result or task error with committed narrative output
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid timeout
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error
• 503: Daemon is unreachable

Verbs

Verb listing, retrieval, programming, and invocation

GET /v1/verbs/{object}

List verbs on an object

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Verb listing
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/verbs/{object}/{name}

Retrieve a single verb

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Verb details
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

POST /v1/verbs/{object}/{name}

Set a verb's program code

Uploads MOO source code for a verb as the authenticated player. This operation does not create daemon connection state.

Requires: X-Moor-Auth-Token

Parameters

Request body (required)

• Content-Type: text/plain

  Example:

  return "Hello, " + argstr + "!";
  

Responses

• 200: Programming result
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error
• 503: Daemon is unreachable

POST /v1/verbs/{object}/{name}/invoke

Invoke a verb and return the result

Calls a verb on the specified object with FlatBuffer- or JSON-encoded arguments. The verb runs as the authenticated player and with that authority. The request creates no daemon connection.

The InvocationResponse contains the result or error and committed root-task output. A failed call includes notifications committed before the error and its traceback. Output from forked tasks is not included. An input request fails the task.

Requires: X-Moor-Auth-Token

Parameters

Request body (required)

• Content-Type: application/x-flatbuffers

• Content-Type: application/json

  Field	Type	Required	Description
  args	array	Yes

  Example:

  {
    "args": [
      {
        "VarInt": {
          "value": 7
        }
      },
      {
        "VarStr": {
          "value": "argument"
        }
      }
    ]
  }
  

Responses

• 200: Verb call result
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid timeout, object CURIE, or request body
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error
• 503: Daemon is unreachable

Properties

Property listing, retrieval, and update

GET /v1/properties/{object}

List properties on an object

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Property listing
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/properties/{object}/{name}

Retrieve a single property value

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Property value
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

POST /v1/properties/{object}/{name}

Update a property value

Sets a property to a new value specified as a MOO literal in the request body (e.g. "hello", 42, {1, 2, 3}).

Requires: X-Moor-Auth-Token

Parameters

Request body (required)

• Content-Type: text/plain

  Example:

  "new value"
  

Responses

• 200: Update result
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE or unparseable literal
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

Objects

Object listing and resolution

GET /v1/objects

List all objects visible to the player

Requires: X-Moor-Auth-Token

Responses

• 200: Object listing
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/objects/query

Query objects with filters

Returns a list of objects matching the provided filters. Internally uses BatchWorldState with a WsQueryObjects action.

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Query results
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/objects/{object}

Resolve an object reference

Resolves a CURIE (e.g. moor:1, moor:system) and returns object details.

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Object details
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid object CURIE
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

POST /v1/batch

Execute multiple world state operations atomically

Submits a list of world state actions to be executed in a single transaction. Supports both FlatBuffers (BatchWorldState table) and JSON payloads. The server rejects the full request if any action cannot be decoded; it never executes a partial batch.

Requires: X-Moor-Auth-Token

Request body (required)

• Content-Type: application/x-flatbuffers

• Content-Type: application/json

  Field	Type	Required	Description
  actions	array	Yes
  rollback	boolean	No

Responses

• 200: Batch execution results
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid request body
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

EventLog

Encrypted event-log history and presentation management

GET /v1/history

Retrieve narrative history

Returns narrative events for the authenticated player. Exactly one of since_seconds, since_event, or until_event must be provided.

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: History events
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid UUID or missing query parameter
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/presentations

List active presentations

Requires: X-Moor-Auth-Token

Responses

• 200: Current presentations
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 401: Missing or invalid auth token
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

DELETE /v1/presentations/{presentation_id}

Dismiss a presentation

Requires: X-Moor-Auth-Token

Parameters

Responses

• 200: Presentation dismissed
  • Content-Type: application/json
• 401: Missing or invalid auth token
• 500: Internal server error

GET /v1/event-log/pubkey

Get event-log encryption public key

Requires: X-Moor-Auth-Token

Responses

• 200: Current public key
  • Content-Type: application/json
• 401: Missing or invalid auth token
• 500: Internal server error

PUT /v1/event-log/pubkey

Set event-log encryption public key

Requires: X-Moor-Auth-Token

Request body (required)

• Content-Type: application/json

  Field	Type	Required	Description
  public_key	string	Yes	age public key

Responses

• 200: Key set
  • Content-Type: application/json
• 400: Missing public_key field
• 401: Missing or invalid auth token
• 500: Internal server error

DELETE /v1/event-log/history

Delete event-log history for the player

Requires: X-Moor-Auth-Token

Responses

• 200: History deleted
  • Content-Type: application/json
• 401: Missing or invalid auth token
• 500: Internal server error

System

Health, version, features, and system properties

GET /v1/system_property/{path}

Read a system property by dotted path

Retrieves a property from $system by path (e.g. server_version). Auth token is optional — unauthenticated requests are allowed.

Parameters

Responses

• 200: Property value
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 400: Invalid property path
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/features

Get server feature flags

Returns the set of features the server supports. Response is cached.

Responses

• 200: Feature flags
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /v1/invoke_welcome_message

Get the server welcome message

Invokes #0:do_login_command with no arguments to produce the welcome/MOTD text shown before login. This is the one call that needs no credentials; it always runs that one verb as #0, and its output is captured and returned.

Responses

• 200: Welcome message
  • Content-Type: application/x-flatbuffers
  • Content-Type: application/json
• 406: Accept header does not include application/x-flatbuffers or application/json
• 500: Internal server error

GET /health

Health check

Returns 200 if the web host is running and has received a daemon ping recently; 503 otherwise.

Responses

• 200: Healthy (empty body)
• 503: No recent daemon ping

GET /version

Get server version

Responses

• 200: Version info
  • Content-Type: application/json

GET /openapi.yaml

OpenAPI specification

Returns this spec (embedded at compile time).

Responses

• 200: OpenAPI 3.1.0 YAML document
  • Content-Type: text/yaml

Webhooks

External webhook receiver (forwarded to MOO)

GET /webhooks/{path}

Receive an external webhook (GET)

The web host forwards the request to the MOO #0:invoke_http_handler verb. It creates no daemon connection state. The MOO verb determines the response status code, body, and content type.

No authentication required — the request runs as the system user. Body limit is 2 MB.

Parameters

Responses

• 200: Webhook handled (status, body, and content type determined by MOO verb)
  • Content-Type: */*
• 404: No webhook handler found
• 408: Webhook handler timed out (30 s)
• 503: Daemon is unreachable

POST /webhooks/{path}

Receive an external webhook (POST)

The web host forwards the request to the MOO #0:invoke_http_handler verb. It creates no daemon connection state. The MOO verb determines the response status code, body, and content type.

No authentication required — the request runs as the system user. Body limit is 2 MB.

Parameters

Request body

• Content-Type: */*

Responses

• 200: Webhook handled (status, body, and content type determined by MOO verb)
  • Content-Type: */*
• 404: No webhook handler found
• 408: Webhook handler timed out (30 s)
• 503: Daemon is unreachable

PUT /webhooks/{path}

Receive an external webhook (PUT)

The web host forwards the request to the MOO #0:invoke_http_handler verb. It creates no daemon connection state. The MOO verb determines the response status code, body, and content type.

No authentication required — the request runs as the system user. Body limit is 2 MB.

Parameters

Request body

• Content-Type: */*

Responses

• 200: Webhook handled (status, body, and content type determined by MOO verb)
  • Content-Type: */*
• 404: No webhook handler found
• 408: Webhook handler timed out (30 s)
• 503: Daemon is unreachable

DELETE /webhooks/{path}

Receive an external webhook (DELETE)

The web host forwards the request to the MOO #0:invoke_http_handler verb. It creates no daemon connection state. The MOO verb determines the response status code, body, and content type.

No authentication required — the request runs as the system user. Body limit is 2 MB.

Parameters

Responses

• 200: Webhook handled (status, body, and content type determined by MOO verb)
  • Content-Type: */*
• 404: No webhook handler found
• 408: Webhook handler timed out (30 s)
• 503: Daemon is unreachable

PATCH /webhooks/{path}

Receive an external webhook (PATCH)

The web host forwards the request to the MOO #0:invoke_http_handler verb. It creates no daemon connection state. The MOO verb determines the response status code, body, and content type.

No authentication required — the request runs as the system user. Body limit is 2 MB.

Parameters

Request body

• Content-Type: */*

Responses

• 200: Webhook handled (status, body, and content type determined by MOO verb)
  • Content-Type: */*
• 404: No webhook handler found
• 408: Webhook handler timed out (30 s)
• 503: Daemon is unreachable