MoonCoAPI documentation

MoonCo API integration

MoonCo exposes an OpenAI-compatible API at:

https://api.moonco.one/v1

All requests use HTTPS and bearer authentication. Set the API key and the model ID issued to your account in your process environment:

export MOONCO_API_KEY="your-api-key"
export MOONCO_MODEL_ID="your-issued-model-id"

Send it on every request as Authorization: Bearer $MOONCO_API_KEY. The examples below also accept MOONCO_API_BASE_URL so they can be checked against a local test route; applications can leave that variable unset.

Chat completions

POST /v1/chat/completions supports this small OpenAI-compatible request subset:

For SDK compatibility, MoonCo also accepts stream_options with include_usage, deprecated max_tokens in place of max_completion_tokens, and n set to 1; usage remains included and only one choice is returned. Other request fields are not part of the public contract and can be rejected.

MoonCo forwards accepted sampling controls to a model endpoint that supports them. These controls can influence generation, but they do not guarantee reproducible output.

Non-streaming curl

curl --fail-with-body --silent --show-error \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/chat/completions" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"model\":\"${MOONCO_MODEL_ID:?Set MOONCO_MODEL_ID to an ID returned by /v1/models}\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with a short greeting.\"}],\"stream\":false}"

Streaming curl

curl --fail-with-body --silent --show-error --no-buffer \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/chat/completions" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"model\":\"${MOONCO_MODEL_ID:?Set MOONCO_MODEL_ID to an ID returned by /v1/models}\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with a short greeting.\"}],\"stream\":true}"

Streaming responses use server-sent events. Each event begins with data: and contains a JSON chat-completion chunk. The stream ends with data: [DONE]. Read incremental text from choices[].delta.content; inspect the final choice finish reason and final usage when present.

OpenAI Python SDK

Install and import the current openai package, then provide MoonCo's API base URL:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONCO_API_KEY"],
    base_url=os.environ.get("MOONCO_API_BASE_URL", "https://api.moonco.one/v1"),
)

response = client.chat.completions.create(
    model=os.environ["MOONCO_MODEL_ID"],
    messages=[{"role": "user", "content": "Reply with a short greeting."}],
)
print(response.choices[0].message.content)

Models

GET /v1/models returns the public model IDs available to the calling key.

curl --fail-with-body --silent --show-error \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/models" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}"

Use a returned data[].id value as model in chat-completion requests. Applications should not depend on the ordering of the returned list.

Account

GET /v1/account uses the same API key and returns its authenticated account summary.

curl --fail-with-body --silent --show-error \
  "${MOONCO_API_BASE_URL:-https://api.moonco.one/v1}/account" \
  --header "Authorization: Bearer ${MOONCO_API_KEY}"

The response includes the account display name, credit totals, estimated remaining credit, exhaustion state, an as_of timestamp, allowed public model IDs, and the calling key's alias and masked identifier. limits.rpm and limits.tpm report the authenticated team's current shared request and token ceilings across all of its keys. retention_policy reports the policy applied prospectively when each new request is admitted: zero-content, 30-days, 90-days, 365-days, or indefinite. Treat as_of as the freshness boundary. These fields are authenticated account data; this documentation does not publish any team's configured values.

Response fields

A non-streaming chat response follows the OpenAI-compatible shape:

The final streaming event uses the same usage shape. Cost is an integer to avoid floating-point money ambiguity. Clients should ignore additional response fields they do not recognize.

Errors and retries

Errors use an HTTP status and a JSON error body. Do not depend on error prose; branch on the status and keep request identifiers when available for support.

Use a small retry limit. A retried chat POST can start a new completion, so retry only when your application can tolerate another generation. Do not attempt to resume a disconnected stream; start a new request if that behavior is acceptable.

API-key safety

For integration support, email support@moonco.io. Do not include API keys, request content, or other secrets.