HTTP API

The HTTP API

The base address, the two keys, the four endpoints you call, and where the API's machine-readable description lives.

Text

https://api.morphscreen.com/v1

Keys

Header	What it is
`X-MorphScreen-Key: ms_live_...`	Your MorphScreen key, on every call. The call counts against your plan. Keep it on your server.
`Authorization: Bearer sk-or-...`	Your own OpenRouter key, when you want a model other than the one in your plan. It goes to OpenRouter and nowhere else, never stored or logged. Leave it out to use the model in your plan.

Endpoint	What it does
`POST /v1/chat/completions`	OpenAI's chat completion, answered in our format, checked and repaired; streamed or whole
`POST /v1/ui`	An AG-UI run, what the web SDK's `connectAgent` reads
`POST /v1/render`	An answer you already have, drawn as HTML (or ops, or the tree) with no model called
`GET /v1/health`	Whether the API is up

Each model call takes the same options: in a morphscreen field for chat completions, in forwardedProps for AG-UI, at the top level for render.

Option	What it does
`packs`	the packs to add to core; every pack when left out, `[]` for core alone
`components`	your own packs (Your own components)
`images`	your own pictures, which the model shows by id
`photos`	your own Pexels, Unsplash or Openverse key, for photos the model asks for
`image_hosts`	more hosts the HTML's pictures may load from
`repair`	repair an answer with errors (default `true`)
`output`	what comes back: `text` or `html` for chat completions, `agui` or `ops` for AG-UI, `html`, `ops` or `tree` for render

The API's OpenAPI 3.1 description is at /v1/openapi.json. Our tests hold the server to it, and these reference pages are generated from it.

Limits and errors has every error and what to do about it.