03 — API Reference

Endpoints

Three endpoints, all OpenAI-compatible. Request validation via Zod. OpenAI-style error responses.

GET /v1/models

List available models. Returns deterministic mock data.

terminal 
$ curl http://localhost:8787/v1/models
200 OK
{
  "object": "list",
  "data": [
    {
      "id": "meowgpt",
      "object": "model",
      "owned_by": "meowgpt"
    }
  ]
}

POST /v1/chat/completions

Chat completions with streaming support. Validates request body with Zod.

Request

json 
{
  "model": "meowgpt",            // required
  "messages": [                  // required, min 1
    { "role": "user", "content": "hello" }
  ],
  "stream": false,               // optional, default false
  "temperature": 0.7,            // optional
  "max_tokens": 256,             // optional
  "delay_ms": 300                // optional, 0-10000. Simulates thinking delay
}

delay_ms controls response latency. Default 300ms. Set to 0 for instant responses in CI. In streaming mode, chunk delay = delay_ms / 4 per token with jitter.

Response

200 OK
{
  "id": "chatcmpl_mock",
  "object": "chat.completion",
  "created": 123456789,
  "model": "meowgpt",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Meow meow 🐱"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2,
    "completion_tokens": 3,
    "total_tokens": 5
  }
}

Streaming

Set "stream": true to receive Server-Sent Events.

200 OK (text/event-stream)
data: {"id":"chatcmpl_mock","object":"chat.completion.chunk","created":123456789,"model":"meowgpt","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl_mock","object":"chat.completion.chunk","created":123456789,"model":"meowgpt","choices":[{"index":0,"delta":{"content":"Meow"},"finish_reason":null}]}

data: {"id":"chatcmpl_mock","object":"chat.completion.chunk","created":123456789,"model":"meowgpt","choices":[{"index":0,"delta":{"content":" meow"},"finish_reason":null}]}

data: {"id":"chatcmpl_mock","object":"chat.completion.chunk","created":123456789,"model":"meowgpt","choices":[{"index":0,"delta":{"content":" 🐱"},"finish_reason":null}]}

data: {"id":"chatcmpl_mock","object":"chat.completion.chunk","created":123456789,"model":"meowgpt","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":2,"completion_tokens":3,"total_tokens":5}}

data: [DONE]

Errors

400 Bad Request
{
  "error": {
    "message": "model: Required; messages: Required",
    "type": "invalid_request_error",
    "code": "invalid_parameters"
  }
}

POST /v1/images/generations

Image generation. Returns URL or base64 SVG. Supports n, size, quality, style.

Request

json 
{
  "prompt": "a cat",             // required
  "model": "meowgpt",            // optional
  "n": 1,                        // optional, 1-10
  "size": "1024x1024",           // optional
  "response_format": "url",      // optional, "url" | "b64_json"
  "quality": "standard",         // optional
  "style": "vivid"               // optional
}

Response

200 OK
{
  "created": 123456789,
  "data": [
    {
      "url": "https://meowgpt.dev/mock-image.png",
      "revised_prompt": "a cat"
    }
  ]
}

Error codes

400

Invalid request body or parameters. Check the error message for details.

404

Route not found. Verify the path and method.

405

Method not allowed on this endpoint.

500

Internal server error. Check server logs.

← Usage Home