Dot2API
Turn your OpenAI Dot into an OpenAI- and Claude-compatible API
English | 简体中文
> [!NOTE]
> This project is for technical research and personal use with your own Dot. Comply with OpenAI's terms of use and local laws; you are solely responsible for how you use it.
> [!WARNING]
> Anyone holding an API key can prompt your Dot, which may have access to your connected apps. Issue keys only to callers you trust as much as yourself. See [Security](SECURITY.md).
## Overview
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.
### Architecture
```mermaid
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
OpenAI SDK · Anthropic SDK · curl"]
subgraph Core["Dot2API"]
direction TB
Compat["Compatibility layer
/v1/chat/completions · /v1/messages"]
Tasks["Task core
Leases · Retries · Deadlines"]
Events["Event outbox
Signed webhooks"]
MCP["MCP endpoint
/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
```
### Core capabilities
| Area | Capabilities |
|---|---|
| APIs | OpenAI Chat Completions, Anthropic Messages, model list, and an asynchronous task API |
| Clients | OpenAI-compatible and Anthropic-compatible SDKs, automation tools, and plain HTTP |
| Streaming | SSE in both dialects, with keep-alives while the Dot works |
| Reliability | Durable tasks, atomic claims, leases, bounded retries, deadlines, and cancellation when the caller disconnects |
| Events | MCP Events subscriptions, callback verification, signed at-least-once webhook delivery |
| Security | Expiring keys stored as fingerprints, scoped identities, rate limits, audit records |
| Operations | One-command setup, health and readiness probes, consistent backups, hardened container image |
### Limitations
A Dot is an agent, not a model endpoint, so the API is compatible in shape rather than in behavior.
| Aspect | Behavior |
|---|---|
| Latency | Seconds to minutes per reply. Requests wait up to 300 seconds by default, then return 504 with a `task_id` to read later |
| Streaming | The whole reply arrives in one delta, not token by token |
| Content | Text only. Images and tool-result blocks return 400 |
| Tool calling | Not supported. `tools` is ignored; the Dot uses its own tools and never returns tool calls |
| Parameters | Sampling parameters and `max_tokens` are accepted and ignored. Token usage is reported as zero |
| Concurrency | One Dot answers one queue. Requests wait in line |
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.
## Quick start
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](docs/deployment.md).
### Docker Compose
```bash
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
```
### Run from source
Python 3.11 or later and [uv](https://docs.astral.sh/uv/) are required.
```bash
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:
```json
{"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.
## Connect your Dot
1. Add an MCP connector pointing at `https:///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:///mcp/`.
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](docs/dot.md).
## API
| Endpoint | Purpose |
|---|---|
| `POST /v1/chat/completions` | OpenAI-compatible chat completion |
| `POST /v1/messages` | Anthropic-compatible message |
| `GET /v1/models` | Model list containing `dot` |
| `POST /v1/tasks` · `GET /v1/tasks/{task_id}` | Asynchronous submission and result retrieval |
| `POST /mcp` | MCP tools and event subscriptions used by the Dot |
| `GET /healthz` · `GET /readyz` | Liveness and readiness |
Credentials are accepted as `Authorization: Bearer ` or `x-api-key: `. Any `model` value is accepted and echoed back.
### curl
```bash
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."}]
}'
```
### OpenAI SDK
```python
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)
```
### Anthropic SDK
```python
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](docs/api.md).
## Configuration
| Variable | Default | Meaning |
|---|---|---|
| `DOT2API_DATA_DIR` | `var` | Database and encryption-key directory |
| `DOT2API_HOST` | `127.0.0.1` | Listen address |
| `DOT2API_PORT` | `8788` | Listen port |
| `DOT2API_QUEUE` | `dot` | Queue the Dot subscribes to |
| `DOT2API_COMPLETION_TIMEOUT` | `300` | Seconds a request waits for the Dot before returning 504 |
| `DOT2API_TASK_TTL` | `3600` | Seconds before an unanswered request expires |
| `DOT2API_RATE_PER_MINUTE` | `120` | Request limit per identity |
| `DOT2API_CAPABILITY_URLS` | disabled | Set to `1` to allow the token in the MCP path |
Additional keys, separate callers, token rotation, and the administrative commands are covered in [Configuration](docs/configuration.md).
## Documentation
- [Connecting a Dot](docs/dot.md)
- [API and MCP reference](docs/api.md)
- [Architecture and delivery semantics](docs/architecture.md)
- [Configuration](docs/configuration.md)
- [Deployment and recovery](docs/deployment.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
## Development
```bash
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
```
## License
MIT. See [LICENSE](LICENSE).