Skip to main content

API

This overview covers the public Codexpertise API contract for first integrations. It avoids provider-specific model lists until those options are verified in production.

Endpoint contract

TODO: verify against sub2api. The request and error examples below use an OpenAI-compatible shape so customers can prepare integrations, but the final endpoint list and response fields must be checked against the deployed sub2api configuration before they are treated as a stable contract.

Base URL​

Use this base URL for API clients:

https://api.codexpertise.com

Do not point user applications at internal infrastructure hosts. Public clients should use the public API domain above.

Authentication​

Send API keys as bearer tokens:

Header
Authorization: Bearer YOUR_API_KEY

Create and manage keys in dash.codexpertise.com. Store keys in environment variables or a secret manager, not in source code.

Request Format​

JSON requests should include Content-Type: application/json. The quickstart uses this first-call shape:

Example request
curl -sS "https://api.codexpertise.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Say hello in one short sentence."
      }
    ]
  }'

TODO: verify against sub2api before documenting additional endpoints, required fields, or model names.

Streaming​

Streaming requests keep the HTTP connection open while tokens are produced. Use streaming only when your client can handle partial output, retries, and network interruptions.

Typical client behavior:

  • Set a request timeout that is long enough for the expected response.
  • Render partial output as it arrives.
  • Treat a broken stream as an incomplete response and retry only when the action is safe to repeat.

TODO: verify against sub2api before publishing the exact streaming request parameter and event format.

Rate Limits​

Codexpertise may apply account, key, plan, and abuse-prevention limits. This documentation publishes numeric limits only after they are confirmed for each plan.

When a limit is hit, the API may return 429 Rate Limited. Reduce concurrency, wait before retrying, and check current usage in the dashboard.

Error Format​

Errors should be handled by HTTP status code first. The response body may include machine-readable details, but clients should not depend on unverified fields yet.

Example error shape
{
  "error": {
    "message": "Request failed.",
    "type": "api_error",
    "code": "upstream_error"
  }
}

TODO: verify against sub2api before documenting the final error schema, request ID field, or retry headers.

Common status codes:

  • 401 Unauthorized: Missing, malformed, expired, or revoked API key.
  • 403 Forbidden: Key is valid but the account, plan, origin, or route is not allowed.
  • 429 Rate Limited: Quota or rate limit exceeded.
  • 5xx Upstream Error: Relay or upstream provider returned a server-side failure.

API Key Rotation​

Rotate keys immediately after a leak, when a teammate leaves, or on a regular security schedule:

  1. Create a new key in the dashboard.
  2. Update local environment variables, CI secrets, and production secret stores.
  3. Deploy or restart clients that read the key at startup.
  4. Send a small test request with the new key.
  5. Revoke the old key after traffic has moved.

Never paste raw API keys or full Authorization headers into logs, tickets, or screenshots.