Developer Reference

DotProd OpenAI-Compatible API Guide

Connection parameters, supported request formats, streaming behavior, error codes, and retention terms.

1. Base URL & Authentication

Connect official OpenAI SDKs, evaluation harnesses, or HTTP clients using a workspace virtual key.

Environment API Base URL: https://dotprod.tech/v1

Authentication Header: Authorization: Bearer sk-...

Supported endpoints: GET /v1/models, POST /v1/sessions, POST /v1/chat/completions, POST /v1/responses (for Codex CLI and OpenAI Responses clients), and POST /v1/messages / POST /v1/messages/count_tokens (for Claude Code and Anthropic Messages clients). Unexposed routes (such as /v1/embeddings or /v1/completions) return HTTP 404.

Supported Models on This Gateway

strange_quark up_quark down_quark

2. Chat Completions & Buffered SSE Screening Behavior

POST /v1/chat/completions — Plain-text chat messages with pre-inference ceiling holds and safety screening.

Important streaming & telemetry limitations:
  • Buffered SSE delivery (full-output pre-release screening): When stream: true is passed on /v1/chat/completions, /v1/responses, or /v1/messages, DotProd returns standard wire-compatible text/event-stream frames so streaming SDKs and coding harnesses (Claude Code, Codex CLI, OpenAI SDK) work without code changes, after buffering, R2-capturing, and screening the complete model response across overlapping moderation windows. First-chunk latency therefore equals full generation + screening time.
  • Text, tool calls & structured outputs: Plain-text messages, function tool calls (tools / tool_choice), and structured outputs (response_format: text, json_object, json_schema) are screened, captured, and budgeted; multimodal binary attachments and upstream persistence (store: true) are rejected with HTTP 400.
  • Usage reporting: Uncached vs. prefix-cached input splits are reported when provided by the upstream model server; when omitted, DotProd records null (displayed as unknown) rather than reporting 0, and reconciles missing usage provisionally until authoritative provider logs arrive.

Python (OpenAI SDK)


          

cURL Example


          

3. Spend Controls & Failure Responses

Prepaid credit balances and UTC monthly spend budgets are enforced independently inside TenantLedgerDO.

  • 400 Bad Request — Invalid UTF-8 JSON, max_tokens out of range, unsupported non-text/tool parameters, or input/output blocked by content policy (code: "content_blocked").
  • 401 Unauthorized — Missing, invalid, blocked, or revoked sk-... virtual API key (type: "authentication_error").
  • 402 Payment Required — Prepaid credit balance is below the conservative request reservation ceiling (code: "insufficient_funds").
  • 403 Forbidden — Requested model is not enabled for your workspace, or the workspace is suspended.
  • 429 Too Many Requests — Aggregate UTC monthly spend budget reached (code: "budget_exceeded") or per-minute RPM limit exceeded (code: "rate_limit_exceeded", includes Retry-After header).
  • 502 / 503 — Upstream inference failure or unavailable content-retention/screening dependency (fail-closed).

Example Error Payload (HTTP 429 Monthly Budget Cap)

{
  "error": {
    "message": "Monthly spend budget (2026-11 UTC) of $50.00 reached ($49.9200 settled/held)",
    "type": "insufficient_quota",
    "code": "budget_exceeded"
  }
}

4. Content Capture, Privacy & Retention Terms

How request inputs, model outputs, and waitlist submissions are stored and audited.

Inference content retention: Before model dispatch and before response release, DotProd captures plain-text request inputs and model outputs to Cloudflare R2 encrypted with AES-256-GCM per-object envelope keys, paired with SHA-256 integrity digests in D1. Raw captures are never exposed via shared admin keys; decryption requires a named, MFA-verified reviewer identity holding an explicit can_read_content grant for the target tenant and a mandatory 8–500 character incident/ticket reason recorded in access_audit.

Waitlist submissions: Email addresses and plan preferences submitted to /waitlist are protected by Cloudflare Turnstile, rate-limited using salted hashes, retained until their configured expiry window (purged automatically by scheduled Worker tasks), and accessible only to MFA-verified staff with audited role grants.