# API Overview

The Gamopanda REST API is versioned and served from:

<pre><code>{import.meta.env.ZUDOKU_PUBLIC_API_BASE_DOMAIN}/api/v1.0</code></pre>

All responses wrap data in a consistent envelope:

```json
{
  "data": { ... }
}
```

Paginated list endpoints include a `paging` object:

```json
{
  "data": [...],
  "paging": {
    "nextOffset": 20,
    "previousOffset": 0,
    "total": 143 // Only present when previousOffset is zero
  }
}
```

## Authentication

Gamopanda supports two authentication flows. Each endpoint lists which flows it accepts under its **Security** section — when multiple flows are listed, any one of them is sufficient.

### API key flow (server-to-server)

Use your account API key and secret for backend / server-to-server calls:

```http
x-api-key: <your-api-key>
x-api-secret: <your-api-secret>
```

Both headers must be sent together.

### End-user flow (client-side)

Use an end-user access token together with the account ID for requests made on behalf of a specific end user (e.g. from a frontend widget):

```http
x-enduser-access-token: <end-user-jwt>
x-account-id: <your-account-uuid>
```

Both headers must be sent together.

| Flow | Required headers |
|---|---|
| **API key** | `x-api-key` + `x-api-secret` |
| **End-user** | `x-enduser-access-token` + `x-account-id` |

## Common query parameters

Most list endpoints support the following query parameters:

| Parameter | Description |
|---|---|
| `fields` | JSON array of field slugs to return, e.g. `["id","name"]` |
| `filters` | JSON-encoded `ComplexCondition` filter object |
| `sortBy` | JSON array of sort params, e.g. `[{"fieldSlug":"createdAt","order":"desc"}]` |
| `offset` | Pagination offset (default `0`) |
| `limit` | Page size — 1–1000 (default `20`) |
| `languageCode` | BCP-47 locale for localised fields, e.g. `en`, `fr` |

## Error responses

All error responses follow a uniform shape:

```json
{
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable description of the error."
  }
}
```

Common HTTP status codes returned:

| Status | Meaning |
|---|---|
| `400` | Bad request — invalid input |
| `401` | Unauthorised — missing or invalid token |
| `403` | Forbidden — insufficient permissions |
| `404` | Not found |
| `409` | Conflict — duplicate record |

## Next steps

Browse the full [API Reference](/api) to explore every endpoint, try requests interactively, and view request/response schemas.