Skip to main content
ccsio.ai

Documentation

Developers

Integrate once. The public Gateway is OpenAI-compatible, region-pinned, and documented below exactly as the contract defines it.

Quickstart

Pick your region — EU, USA or LATAM — and the example follows: the exact Gateway base URL, the OpenAI-compatible standard client, and a clearly labeled placeholder key. You create and manage your API key in your region's Console. The first available model is qwen-3-8 (Qwen 3.8, 320K context). Access is on the waitlist: join, pick your region, and your key arrives when that region opens.

# Region endpoint — OpenAI-compatible /v1 base URL
export CCSIO_AI_BASE_URL=https://api.eu.ccsio.ai/v1
export CCSIO_AI_API_KEY=<your-api-key>            # placeholder, issued with your region

import os
from openai import OpenAI                          # the standard OpenAI client

client = OpenAI(
    base_url=os.environ["CCSIO_AI_BASE_URL"],
    api_key=os.environ["CCSIO_AI_API_KEY"],
)

response = client.chat.completions.create(
    model="qwen-3-8",   # first available model, 320K context
    messages=[{"role": "user", "content": "Hello"}],
)

Regional endpoints and Consoles

Your region choice maps one-to-one to your Gateway and your Console: EU — https://api.eu.ccsio.ai/v1 with https://console.eu.ccsio.ai; USA — https://api.us.ccsio.ai/v1 with https://console.us.ccsio.ai; LATAM — https://api.latam.ccsio.ai/v1 with https://console.latam.ccsio.ai. No silent cross-region routing: your key, your calls, and your data stay in the region you selected.

RegionGateway endpointConsole
EUhttps://api.eu.ccsio.ai/v1console.eu.ccsio.ai
LATAMhttps://api.latam.ccsio.ai/v1console.latam.ccsio.ai
USAhttps://api.us.ccsio.ai/v1console.us.ccsio.ai

Live Gateway reference

The operations below are generated from the published Gateway contract — method, path, parameters, and error contract exactly as deployed. We document only what you can call today; nothing speculative ships as an instruction.

Authentication

Authorization: Bearer <JWT>x-api-key: <api-key>

Supply one credential per request — never both. Credentials are created and managed in your region's Console; the examples above use placeholders only.

  1. POST/v1/chat/completionsoperationId: chatCompletionsSSE

    Stream a chat completion

    Accepts only streaming requests. stream must be true; false or omitted returns 400 with code non-streaming-not-supported before any SSE headers are committed. Successful responses contain SSE data frames and terminate with data: [DONE]. Pre-commit failures use the JSON ErrorEnvelope rather than SSE.

    Parameters

    nameinrequireddescription
    X-Data-RegionheaderrequiredDeclared data region used during placement.
    X-Request-IDheaderrequiredRequired request ULID. Lowercase input is accepted; the response X-Request-ID header uses the canonical uppercase form.
    X-ResidencyheaderrequiredDeclared request residency used during placement.
    X-Trace-IDheaderrequiredRequired trace correlation identifier.

    Request body: application/json — schema ChatRequest

    Responses

    • 200SSE stream. Frames are data: {"content":"..."}, data: {"usage":{"prompt_tokens":n,"completion_tokens":n}}, data: {"content":"...","usage":{"prompt_tokens":n,"completion_tokens":n}}, or after a committed-stream failure data: {"error":"..."}. The terminal frame is data: [DONE].
    • 400Client refusal unrelated to authentication, including malformed input, a denied or failed request.
    • 401Step-1 credential refusal: missing credentials, rejected or invalid credentials, or duplicate/both credential forms.
    • 404The requested resource or path was not found.
    • 405The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
    • 500Platform failure, rendered without internal cause details.
    • 502Failure in an external dependency or malformed provider response.

    Example

    curl -N https://api.eu.ccsio.ai/v1/chat/completions \
-H "Authorization: Bearer $CCSIO_AI_API_KEY"   -H "X-Request-ID: 01J9ZK8WQ3V6X4M2T5R7N1B8C0"   -H "X-Trace-ID: <your-trace-id>"   -H "X-Residency: <your-region>"   -H "X-Data-Region: <your-region>"   -H "Content-Type: application/json"
  -d '{"model":"qwen-3-8","stream":true,"messages":[{"role":"user","content":"Hello"}]}'
  2. POST/v1/responsesoperationId: createResponsesSSE

    Create a response (OpenAI-compatible)

    Creates a response through a qualified responses deployment. The input is reduced to a single prompt at decode time (the authority rule): a string input is verbatim; an items input is the items in array order, each item's string content verbatim or its input_text parts concatenated in order, item texts joined by a blank line; a non-empty instructions string is prepended before a blank line. The twelve functional fields (tools, tool_choice, tool_usage, parallel_tool_calls, previous_response_id, conversation, background, text, reasoning, truncation, safety, store) are refused on presence with the pinned responses-<field>-not-supported code; inert parameters (metadata, user) are tolerated and ignored. Malformed or empty provider response data returns 502 with code responses-body-malformed or responses-output-missing. Unknown provider usage is represented by zero for all three usage fields.

    Parameters

    nameinrequireddescription
    X-Data-RegionheaderrequiredDeclared data region used during placement.
    X-Request-IDheaderrequiredRequired request ULID. Lowercase input is accepted; the response X-Request-ID header uses the canonical uppercase form.
    X-ResidencyheaderrequiredDeclared request residency used during placement.
    X-Trace-IDheaderrequiredRequired trace correlation identifier.

    Request body: application/json — schema ResponsesRequest

    Responses

    • 200The SSE stream (stream: true) or the final response object (stream: false).
    • 400Client refusal unrelated to authentication, including malformed input, a denied or failed request.
    • 401Step-1 credential refusal: missing credentials, rejected or invalid credentials, or duplicate/both credential forms.
    • 404The requested resource or path was not found.
    • 405The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
    • 500Platform failure, rendered without internal cause details.
    • 502Failure in an external dependency or malformed provider response.

    Example

    curl https://api.eu.ccsio.ai/v1/responses \
-H "Authorization: Bearer $CCSIO_AI_API_KEY"   -H "X-Request-ID: 01J9ZK8WQ3V6X4M2T5R7N1B8C0"   -H "X-Trace-ID: <your-trace-id>"   -H "X-Residency: <your-region>"   -H "X-Data-Region: <your-region>"   -H "Content-Type: application/json"
  -d '{"model":"qwen-3-8","input":"Hello"}'
  3. POST/v1/embeddingsoperationId: createEmbeddings

    Create embeddings

    Creates embeddings through a qualified embeddings deployment. Malformed or empty provider embedding data returns 502 with code embedding-body-malformed or embedding-data-missing. Unknown provider usage is represented by zero for all three usage fields.

    Parameters

    nameinrequireddescription
    X-Data-RegionheaderrequiredDeclared data region used during placement.
    X-Request-IDheaderrequiredRequired request ULID. Lowercase input is accepted; the response X-Request-ID header uses the canonical uppercase form.
    X-ResidencyheaderrequiredDeclared request residency used during placement.
    X-Trace-IDheaderrequiredRequired trace correlation identifier.

    Request body: application/json — schema EmbeddingsRequest

    Responses

    • 200Embedding list and the usage from the metered provider attempt.
    • 400Client refusal unrelated to authentication, including malformed input, a denied or failed request.
    • 401Step-1 credential refusal: missing credentials, rejected or invalid credentials, or duplicate/both credential forms.
    • 404The requested resource or path was not found.
    • 405The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
    • 500Platform failure, rendered without internal cause details.
    • 502Failure in an external dependency or malformed provider response.

    Example

    curl https://api.eu.ccsio.ai/v1/embeddings \
-H "Authorization: Bearer $CCSIO_AI_API_KEY"   -H "X-Request-ID: 01J9ZK8WQ3V6X4M2T5R7N1B8C0"   -H "X-Trace-ID: <your-trace-id>"   -H "X-Residency: <your-region>"   -H "X-Data-Region: <your-region>"   -H "Content-Type: application/json"
  -d '{"model":"qwen-3-8","input":"Hello"}'
  4. GET/v1/modelsoperationId: listModels

    List active published models

    Returns the verified tenant's active published models, deduplicated by model id. Enumeration is authenticated but is not grant-gated. A catalog read failure such as bundle-not-cached returns 400.

    Parameters

    nameinrequireddescription
    X-Request-IDheaderoptionalOptional case-insensitive ULID for model listing. Lowercase input is accepted and canonicalized to uppercase in the response X-Request-ID header; when the header is absent or invalid, middleware mints the request context and response id.

    Responses

    • 200The tenant's model list.
    • 400Client refusal unrelated to authentication, including malformed input, a denied or failed request.
    • 401Step-1 credential refusal: missing credentials, rejected or invalid credentials, or duplicate/both credential forms.
    • 404The requested resource or path was not found.
    • 405The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
    • 500Platform failure, rendered without internal cause details.
    • 502Failure in an external dependency or malformed provider response.

    Example

    curl https://api.eu.ccsio.ai/v1/models \
  -H "Authorization: Bearer $CCSIO_AI_API_KEY"

Authentication

The Gateway defines two credential alternatives — supply one, never both: a Bearer JWT verified against your issuer's JWKS, or the x-api-key header carrying your tenant API key. You create and manage credentials in your region's Console. Nothing on this page is a live credential: every key in the examples is a labeled placeholder.

Platform APIs coming next

Identity, Memory, Metering, Models, and Audit are designed and under construction; they are not public yet, and there are no live endpoints for them here. The roadmap tells you what ships next and at what stage.

View the roadmap

Developer FAQ

Is the API OpenAI-compatible?
Yes. The Gateway speaks OpenAI-compatible contracts: chat completions and responses as SSE streams, embeddings as JSON, and a model list. Point the standard OpenAI client at your region's /v1 base URL.
How do I authenticate?
With a Bearer JWT or the x-api-key header — one of the two, verified against your region. You create and manage credentials in your region's Console: console.eu.ccsio.ai, console.us.ccsio.ai, or console.latam.ccsio.ai. The examples on this page use placeholders only.
Which operations exist in the public Gateway?
POST /v1/chat/completions (SSE stream), POST /v1/responses, POST /v1/embeddings, and GET /v1/models — the four operations of the published contract. The control-plane surfaces (Identity, Memory, Metering, Models, Audit) are on the roadmap, not public.
Where does my region's data run?
Pinned to your chosen region — EU, USA, or LATAM. Your key is scoped to that region's endpoint, and calls are never moved between regions implicitly.

Get your first API key

The waitlist is the path: account, region, key.