Dot2API

Turn your OpenAI Dot into an OpenAI- and Claude-compatible API

English | 简体中文

Dot2API is a self-hosted gateway that exposes one OpenAI Dot through the OpenAI Chat Completions and Anthropic Messages formats. Point an existing SDK at it: each request is queued, your Dot is woken through MCP Events, it claims and answers the request over MCP, and the reply comes back as a normal completion.

Unlike most 2API projects, Dot2API does not reverse-engineer a web interface and never touches your OpenAI credentials. It uses the public MCP 2.0 connector and Events protocol, and it never calls a model itself.

flowchart LR
    classDef access fill:#e1f5fe,stroke:#01579b
    classDef core fill:#fff3e0,stroke:#e65100
    classDef infra fill:#e8f5e9,stroke:#1b5e20
    classDef upstream fill:#fce4ec,stroke:#880e4f

    Clients["API clients<br/>OpenAI SDK · Anthropic SDK · curl"]

    subgraph Core["Dot2API"]
        direction TB
        Compat["Compatibility layer<br/>/v1/chat/completions · /v1/messages"]
        Tasks["Task core<br/>Leases · Retries · Deadlines"]
        Events["Event outbox<br/>Signed webhooks"]
        MCP["MCP endpoint<br/>/mcp"]
        Compat --> Tasks
        Tasks --> Events
        MCP --> Tasks
    end

    Database[("SQLite")]
    Dot["OpenAI Dot"]

    Clients -->|request| Compat
    Compat -.->|reply| Clients
    Events -->|task.available| Dot
    Dot -->|claim_task / complete_task| MCP
    Tasks --> Database

    class Clients access
    class Compat,Tasks,Events,MCP core
    class Database infra
    class Dot upstream

A Dot is an agent, not a model endpoint, so the API is compatible in shape rather than in behavior.

This makes Dot2API a good fit for scheduled jobs, automation workflows, custom bots, and delegating a task from another agent. It is not a model backend for coding agents such as Codex or Claude Code, or for real-time chat front ends.

A Dot connects from OpenAI's network, so the service needs a public HTTPS URL. Both options below bind to loopback; put a TLS reverse proxy in front. See Deployment.

git clone https://github.com/Pluviobyte/dot2api.git
cd dot2api

docker compose build
docker compose run --rm dot2api init
docker compose run --rm dot2api setup
docker compose up -d

Python 3.11 or later and uv are required.

uv sync --frozen --no-dev
uv run --no-sync dot2api init
uv run --no-sync dot2api setup
uv run --no-sync dot2api serve

setup prints two credentials once; only their fingerprints are stored:

{"api_key": "d2a_...", "dot_token": "d2a_...", "queue": "dot"}

• api_key is what callers put in their SDK.
• dot_token is what the Dot uses to reach the MCP endpoint.

1. Add an MCP connector pointing at https://<host>/mcp with dot_token as the bearer credential. If the connector cannot send an authorization header, start the server with DOT2API_CAPABILITY_URLS=1 and use https://<host>/mcp/<dot_token>.
2. Ask the Dot to watch the task.available event on queue dot.
3. Give the Dot its standing instructions: list queued tasks, claim one, answer the conversation, complete the task.

The full walkthrough, a ready-to-paste instruction prompt, and troubleshooting are in Connecting a Dot.

Credentials are accepted as Authorization: Bearer <api_key> or x-api-key: <api_key>. Any model value is accepted and echoed back.

curl https://dot2api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dot",
    "messages": [{"role": "user", "content": "Summarize my unread mail from today."}]
  }'

from openai import OpenAI

client = OpenAI(base_url="https://dot2api.example.com/v1", api_key=API_KEY, timeout=600)
reply = client.chat.completions.create(
    model="dot",
    messages=[{"role": "user", "content": "Summarize my unread mail from today."}],
)
print(reply.choices[0].message.content)

from anthropic import Anthropic

client = Anthropic(base_url="https://dot2api.example.com", api_key=API_KEY, timeout=600)
reply = client.messages.create(
    model="dot",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize my unread mail from today."}],
)
print(reply.content[0].text)

Keep the client timeout above the completion timeout, or set stream to true so keep-alives hold the connection open. Request and response details are in the API reference.

Additional keys, separate callers, token rotation, and the administrative commands are covered in Configuration.

• Connecting a Dot
• API and MCP reference
• Architecture and delivery semantics
• Configuration
• Deployment and recovery
• Security policy
• Contributing

uv sync --frozen
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python -m build
uv run python scripts/check_release.py

MIT. See LICENSE.