Quickstart

This guide helps a new user make the first Codexpertise API request without contacting support.

Endpoint contract

TODO: verify against sub2api. The examples below use the OpenAI-compatible POST /v1/chat/completions request shape. If your dashboard shows a different first-call endpoint, keep the same API base URL and bearer token pattern, then use the endpoint shown there.

1. Sign In

Register or sign in at dash.codexpertise.com. Use the account that owns the quota or billing plan you want to test.

2. Create An API Key

Open the dashboard API key area and create a new key for your local test. Copy it once, store it in a safe place, and use YOUR_API_KEY as the placeholder in the examples below.

3. Set The API Base URL

Use this base URL for API clients:

https://api.codexpertise.com

For local testing, set environment variables before running examples:

Environment

export CODEXPERTISE_API_KEY="YOUR_API_KEY"
export CODEXPERTISE_BASE_URL="https://api.codexpertise.com"
export CODEXPERTISE_MODEL="YOUR_MODEL"

Use the model name available to your account or plan. This guide intentionally does not list models until the production model catalog is verified.

4. Send A curl Request

curl

curl -sS "$CODEXPERTISE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $CODEXPERTISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Say hello in one short sentence."
      }
    ]
  }'

A successful response should return JSON from the relay. If you receive an error, check the troubleshooting section below before rotating keys or opening a support ticket.

5. Send A Node.js Request

This example uses the built-in fetch available in current Node.js versions.

quickstart.mjs

const apiKey = process.env.CODEXPERTISE_API_KEY;
const baseURL = process.env.CODEXPERTISE_BASE_URL ?? "https://api.codexpertise.com";
const model = process.env.CODEXPERTISE_MODEL;

if (!apiKey || !model) {
  throw new Error("Set CODEXPERTISE_API_KEY and CODEXPERTISE_MODEL first.");
}

const response = await fetch(`${baseURL}/v1/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model,
    messages: [
      {
        role: "user",
        content: "Say hello in one short sentence."
      }
    ]
  })
});

const body = await response.text();

if (!response.ok) {
  throw new Error(`Request failed: ${response.status} ${body}`);
}

console.log(JSON.parse(body));

Run it with:

CODEXPERTISE_API_KEY="YOUR_API_KEY" \
CODEXPERTISE_BASE_URL="https://api.codexpertise.com" \
CODEXPERTISE_MODEL="YOUR_MODEL" \
node quickstart.mjs

6. Send A Python Request

This example uses the Python standard library, so no package install is needed.

quickstart.py

import json
import os
import urllib.request


api_key = os.environ["CODEXPERTISE_API_KEY"]
base_url = os.environ.get("CODEXPERTISE_BASE_URL", "https://api.codexpertise.com").rstrip("/")
model = os.environ["CODEXPERTISE_MODEL"]

payload = {
    "model": model,
    "messages": [
        {
            "role": "user",
            "content": "Say hello in one short sentence.",
        }
    ],
}

request = urllib.request.Request(
    f"{base_url}/v1/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request, timeout=60) as response:
    print(json.dumps(json.loads(response.read()), indent=2))

Run it with:

CODEXPERTISE_API_KEY="YOUR_API_KEY" \
CODEXPERTISE_BASE_URL="https://api.codexpertise.com" \
CODEXPERTISE_MODEL="YOUR_MODEL" \
python3 quickstart.py

7. Configure Codex CLI Or A Coding Agent

Many coding agents support OpenAI-compatible environment variables. Use placeholders first, then move the values into your shell profile, CI secret store, or local secret manager.

OpenAI-compatible environment

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.codexpertise.com"
export OPENAI_MODEL="YOUR_MODEL"

If your agent uses a config file instead of environment variables, keep the same values:

agent-config.example.yaml

api:
  base_url: "https://api.codexpertise.com"
  api_key: "YOUR_API_KEY"
  model: "YOUR_MODEL"

TODO: verify against sub2api and the specific Codex CLI or coding-agent client before documenting client-specific config keys as a stable contract.

Common Errors

401 Unauthorized

The API key is missing, malformed, expired, or copied with extra spaces. Confirm that the request includes Authorization: Bearer YOUR_API_KEY after replacing the placeholder with your real key.

403 Forbidden

The key is valid, but the account, plan, origin, or route is not allowed to use the requested API. Check dashboard access, quota ownership, and whether the route is enabled for your plan.

429 Rate Limited

The account has exceeded a rate limit or quota window. Wait before retrying, reduce parallel requests, and check usage in the dashboard.

5xx Upstream Error

The relay or upstream provider returned a server error. Retry with backoff. If the issue persists, save the timestamp and request ID if available, but do not share raw API keys or full Authorization headers.

Streaming interrupted

The stream was cut off by the client, network, proxy, timeout, or upstream provider. Retry once, test a non-streaming request, and reduce response length when possible.

Security Reminders

• Do not commit API keys to git.
• Use environment variables or a secret manager for local and production use.
• If a key leaks, rotate it immediately in the dashboard and remove the leaked value from logs, tickets, screenshots, and repository history.