The Delegation API

The Delegation exposes two APIs: the AI Gateway (OpenAI-compatible, routes to Claude / OpenAI / Gemini) and the Platform API (REST, manages projects, tasks, conversations, and files). Both share the same base domain.

Authentication

Both APIs use Bearer tokens in the Authorization header, but they come from different sources:

curl https://gateway.malcolmstone.io/v1/chat/completions \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"us.anthropic.claude-sonnet-4-6","messages":[{"role":"user","content":"Hello"}]}'

SDKs & libraries

Because the Gateway is OpenAI-compatible, any OpenAI SDK works out of the box — just override the base URL and API key.

OpenAI SDK (Python & TypeScript)

The most common integration path. Works with streaming, tool calls, and all modalities.

# The gateway is drop-in compatible with the OpenAI API.
# Just point base_url at the gateway.
curl https://gateway.malcolmstone.io/v1/chat/completions \\n  -H "Authorization: Bearer gw-your-key" ...

Vercel AI SDK

Use the @ai-sdk/openai provider pointed at the gateway. Supports streaming via streamText, structured output via generateObject, and React hooks.

# Use the openai provider pointed at the gateway
# (install: npm i ai @ai-sdk/openai)

Other SDKs

Any library that accepts a base_url / baseURL override works: LangChain, LlamaIndex, Instructor, Marvin, Guidance, etc. The gateway passes through the OpenAI request schema unchanged.

Quickstart

Three steps to your first API call:

1. Sign up for a developer account at delegation.malcolmstone.io/auth
2. Go to Dashboard → API Keys and issue a key
3. Send your first request:

curl https://gateway.malcolmstone.io/v1/chat/completions \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "us.anthropic.claude-sonnet-4-6",
    "messages": [
      { "role": "system",  "content": "You are a concise assistant." },
      { "role": "user",    "content": "Explain the delegation pattern" }
    ],
    "max_tokens": 256
  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "us.anthropic.claude-sonnet-4-6",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "The delegation pattern ..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 28, "completion_tokens": 142, "total_tokens": 170 }
}

Chat completions

The primary endpoint. Accepts a conversation history and returns the next assistant message.

Context headers

Optional headers tag usage records so you can filter by session, project, or task in your dashboard.

Function calling

Pass a tools array to let the model call functions you define. When the model decides to call a function, the response includes a tool_calls array — your code executes the function and sends the result back as a tool message.

curl https://gateway.malcolmstone.io/v1/chat/completions \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "us.anthropic.claude-sonnet-4-6",
    "messages": [{"role":"user","content":"What is the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type":"string","description":"City name"}
          },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Multi-turn tool loop

Continue the conversation by appending the assistant's tool_calls message and your tool result, then sending the full history again:

// 1. Model response with tool call
{ "choices": [{ "message": {
  "role": "assistant",
  "tool_calls": [{ "id": "call_abc", "type": "function",
    "function": { "name": "get_weather", "arguments": "{"city":"Paris"}" }}]
}}]}

// 2. Your follow-up request — append both messages
{ "messages": [
  { "role": "user",      "content": "What is the weather in Paris?" },
  { "role": "assistant", "tool_calls": [{ "id": "call_abc", ... }] },
  { "role": "tool",      "tool_call_id": "call_abc", "content": "18°C, partly cloudy" }
]}

Vision & multimodal

Send images alongside text by using an array for the content field. Supported models: us.amazon.nova-pro-v1:0, us.anthropic.claude-sonnet-4-6, us.amazon.nova-lite-v1:0, and others.

curl https://gateway.malcolmstone.io/v1/chat/completions \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "us.amazon.nova-pro-v1:0",
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text",      "text": "What is in this image?" },
        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
      ]
    }]
  }'

Streaming

Add stream: true to receive tokens via Server-Sent Events as they are generated. Each line is data: {chunk}. The stream ends with data: [DONE].

curl https://gateway.malcolmstone.io/v1/chat/completions \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"us.anthropic.claude-sonnet-4-6","stream":true,"messages":[{"role":"user","content":"Write a haiku"}]}'

Chunk schema

// Each SSE chunk
data: {
  "id": "chatcmpl-abc",
  "object": "chat.completion.chunk",
  "choices": [{
    "index": 0,
    "delta": { "role": "assistant", "content": "The " },
    "finish_reason": null
  }]
}

// Final chunk
data: { ..., "choices": [{ "delta": {}, "finish_reason": "stop" }] }
data: [DONE]

Embeddings

Convert text into dense vector representations for semantic search, clustering, and retrieval-augmented generation.

curl https://gateway.malcolmstone.io/v1/embeddings \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"amazon.titan-embed-text-v2:0","input":"The delegation pattern in AI"}'

{
  "object": "list",
  "data": [{
    "object":    "embedding",
    "index":     0,
    "embedding": [0.0023064255, -0.009327292, ...]
  }],
  "model": "amazon.titan-embed-text-v2:0",
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

Image generation

curl https://gateway.malcolmstone.io/v1/images/generations \
  -H "Authorization: Bearer gw-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"stability.stable-image-core-v1:1","prompt":"A futuristic delegation of AI agents","size":"1024x1024"}'

Audio

Text-to-speech and speech-to-text via Whisper.

Models

Use GET /v1/models to fetch the live list. Prices shown per 1 million tokens.

Platform API

The Platform API manages your workspace: projects, tasks, conversations, files, and billing. All endpoints are authenticated with a session token sent as Authorization: Bearer <access_token>. Scripts and CLIs get one from POST /api/auth with { email, password } (refresh with PUT /api/auth, revoke with DELETE /api/auth); in the browser the signed-in session cookie is sent automatically.

# 1. Exchange your credentials for a session token
TOKEN=$(curl -s -X POST https://delegation.malcolmstone.io/api/auth \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"…"}' | jq -r .access_token)

# 2. Send it as a Bearer token
curl https://delegation.malcolmstone.io/api/projects \
  -H "Authorization: Bearer $TOKEN"

Projects

Projects are the top-level container for teams, tasks, conversations, and results.

Tasks

Tasks are units of work assigned to agents within a project.

Conversations

Each project has one conversation thread — a history of messages between the user and agents.

File storage

Upload, manage, and share files. Files can be public (CDN-hosted, permanent URL) or private (signed URL, time-limited access).

API keys

Issue and revoke gateway API keys programmatically or from the developer dashboard.

OpenAPI spec

The full OpenAPI 3.0 specification for both the Gateway API and Platform API is available as machine-readable JSON. Import it into Postman, Insomnia, Swagger UI, or any OpenAPI-compatible tool.

Import into Postman

1. Open Postman → Import
2. Select "Link" and paste: https://delegation.malcolmstone.io/api/openapi.json
3. Set the Authorization variable to your gateway key or session token

Import into Insomnia

1. Application menu → Import / Export → Import Data
2. Choose "From URL" and paste the spec URL

Pricing

Developer accounts are fully à la carte — charged only for actual usage, no monthly minimums.

Model costs per token are listed in the Models table above. All prices in USD.

Errors & rate limits

Both APIs use standard HTTP status codes and return errors as { "error": "message" } JSON.

Rate limits

Each gateway key defaults to 60 requests / minute. Set a custom rate_limit when issuing a key (up to your plan maximum). Requests exceeding the limit return 429 with a Retry-After: N header.

Idempotency

POST requests to the Platform API do not support idempotency keys. For safe retries, check whether the resource already exists via a GET before issuing a POST.

Changelog