The Mieza API lets you integrate strategic reasoning into your applications. This guide covers authentication, base URLs, request conventions, and error handling.

## Base URL

All API requests go through the Echelon edge service:

```
https://mieza.ai/api/
```

GTO (Game Theory Optimizer) endpoints are proxied at:

```
https://mieza.ai/v1/
```

## Authentication

Most endpoints require authentication via a Personal Access Token (PAT). See [API Access Tokens](/docs/api-tokens) for how to create one.

Include your token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer tt_YOUR_TOKEN_HERE" \
     https://mieza.ai/v1/games/nf
```

A few endpoints are public and don't require authentication:
- `POST /v1/nf-solve` — ephemeral game solving
- `GET /v1/policies/catalog` — list available policies

## Request Format

- **Content-Type**: `application/json` for all request bodies
- **Accept**: `application/json` for all responses
- **Method conventions**: `GET` to read, `POST` to create, `PATCH` to update, `DELETE` to remove

## Response Format

### Success Responses

Successful responses return the resource directly:

```json
{
  "id": "gt_nfg_abc123",
  "name": "Prisoner's Dilemma",
  "players": ["Alice", "Bob"],
  "equilibria": [...]
}
```

### List Responses

All list endpoints use a pagination envelope:

```json
{
  "games": [...],
  "meta": {
    "limit": 20,
    "has_more": true
  }
}
```

Use `offset` and `limit` query parameters to paginate. Check `meta.has_more` to know if more results exist.

### Error Responses

Errors return a consistent structure:

```json
{
  "error": {
    "cause": "not-found",
    "message": "Game not found"
  }
}
```

## Error Codes

| HTTP Status | Cause | Meaning |
|---|---|---|
| 400 | `bad-request` | Invalid request body or parameters |
| 401 | `unauthorized` | Missing or invalid authentication token |
| 403 | `access-denied` | Valid token but insufficient permissions |
| 404 | `not-found` | Resource does not exist |
| 409 | `conflict` | Resource already exists or state conflict |
| 422 | `validation-error` | Request body fails schema validation |
| 429 | `rate-limited` | Too many requests — back off and retry |
| 500 | `internal-error` | Server error — safe to retry |

### Handling Errors

- **4xx errors**: Fix the request. The `message` field describes what's wrong.
- **5xx errors**: Retry with exponential backoff. These are transient.
- **401**: Your token may have expired. Generate a new one in Settings → Access Tokens.
- **429**: You've hit a rate limit. Wait and retry. Paid plans have higher limits.

## Interactive API Docs

The full OpenAPI specification is available at:

- **Swagger UI**: [mieza.ai/swagger-ui](https://mieza.ai/swagger-ui) — interactive, browser-based API explorer
- **OpenAPI spec**: [mieza.ai/openapi.yaml](https://mieza.ai/openapi.yaml) — machine-readable spec for code generation

## Key API Areas

| Area | Base Path | Description |
|---|---|---|
| Normal-Form Games | `/v1/games/nf` | Solve games, record plays, manage policies |
| Game Analysis | `/v1/plays` | Browse and export analyzed plays |
| Import Sessions | `/v1/import-sessions` | Upload game files for analysis |
| Agents | `/api/agents` | Create and manage AI strategists |
| Conversations | `/api/conversations` | Chat with agents programmatically |
| Tokens | `/api/tokens` | Manage API access tokens |

## Rate Limits

Rate limits depend on your subscription plan:

| Plan | Requests per minute | Monthly token quota |
|---|---|---|
| Arcade (Free) | 60 | 100K tokens |
| Pro | 300 | 5M tokens |
| Elite | 300 | 15M tokens |
| Team (per seat) | 300 | 5M tokens |
| Business (per seat) | 300 | 15M tokens |

When you hit a rate limit, the response includes a `Retry-After` header indicating how long to wait.

## SDKs

Official client libraries are available:

- **Python**: [mieza-api-python](https://github.com/mieza-ai/mieza-api-python) — auto-generated from the OpenAPI spec
- **Clojure**: [mieza-api-clj](https://github.com/mieza-ai/mieza-api-clj) — Clojure client via `:git/url` dependency

## See also
- [API Access Tokens](/docs/api-tokens) — creating and managing tokens
- [Solving Your First Game](/docs/solving-your-first-game) — API tutorial with examples
- [MCP Integration](/docs/mcp-integration) — use the API from Cursor or Claude Desktop