# API overview

The Foxora gateway is a single HTTP API that routes requests to whichever model you choose. It speaks the same shape as OpenAI's chat completions endpoint, with extra Foxora-specific routes for account, usage, and models.

## Base URL

```
https: //api.foxora.ai/v1
```

Every endpoint described in these docs is relative to that base URL. We version with a leading /v1; breaking changes get a new path segment.

## Conventions

- Requests and responses are JSON. Set Content-Type: application/json.
- Authentication is via Authorization: Bearer <token>. See Authentication.
- All timestamps are ISO 8601 in UTC.
- IDs are opaque strings — don’t parse them.

## Errors

Errors return a non-2xx status with a JSON body of the form:

```
{
  "error": {
    "code": "invalid_request",
    "message": "The 'model' field is required.",
    "param": "model"
  }
}
```

### Common status codes

- 400 — malformed request body or missing fields.
- 401 — missing or invalid auth token.
- 402 — spend limit reached or no payment method on file.
- 403 — the token is valid but not allowed to perform this action.
- 404 — resource (model, agent, key) doesn’t exist.
- 429 — rate-limited. Back off and retry.
- 5xx — gateway or upstream provider error. Retry with exponential backoff.

## Rate limits

Limits are per account, not per key. Default ceilings:

When you hit a limit you’ll get a 429 with a Retry-After header (seconds).

## SDKs

Because the chat completions surface is OpenAI-compatible, you can point the official OpenAI SDK at Foxora by overriding baseURL:

```
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FOXORA_API_KEY,
  baseURL: "https://api.foxora.ai/v1",
});
```

```
pip install openai

# in your code:
# from openai import OpenAI
# client = OpenAI(api_key=os.environ["FOXORA_API_KEY"],
#                 base_url="https://api.foxora.ai/v1")
```

> Migrating from OpenAI?In most cases you only need to change two environment variables: OPENAI_API_KEY → your Foxora key, and OPENAI_BASE_URL → https://api.foxora.ai/v1.