# Getting Started with the FloQast v2 API

The FloQast v2 API follows consistent patterns across all endpoints. This page covers the concepts you need before making your first request.

## Authentication

All FloQast API requests require a valid API key passed in the `x-api-key` header:


```bash
curl "https://apix.floqast.app/v2/core/users" \
  -H "x-api-key: <your-api-key>"
```

Contact your administrator to generate API keys. Each key has scoped permissions — use the minimum required scopes for your integration.

## Response Envelope

Every response — success or error — uses the same `{ data, errors, metadata }` envelope:


```json
{
  "data": { ... },
  "errors": [],
  "metadata": {
    "pagination": {
      "totalCount": 42,
      "limit": 25,
      "offset": 0,
      "hasMore": true
    },
    "links": {
      "self": "/v2/core/users?limit=25&offset=0",
      "next": "/v2/core/users?limit=25&offset=25",
      "prev": null
    }
  }
}
```

| Field | Description |
|  --- | --- |
| `data` | The response payload. Object for single resources, array for collections. |
| `errors` | Always empty on success. Contains structured error objects on failure. |
| `metadata` | Contains `pagination` and navigation `links`. Omitted when empty (e.g. single-resource responses). |


## Pagination

List endpoints use offset-based pagination via `limit` and `offset` query parameters:

| Parameter | Default | Max | Description |
|  --- | --- | --- | --- |
| `limit` | 25 | 100 | Number of items to return |
| `offset` | 0 | — | Number of items to skip |



```bash
# Page 2 of results (items 26–50)
curl "https://apix.floqast.app/v2/core/users?limit=25&offset=25" \
  -H "x-api-key: <your-api-key>"
```

Use `metadata.pagination.hasMore` to determine if additional pages exist.

## Error Handling

Errors follow [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457). All error responses use `{ errors: [...] }` — always an array, even for a single error:


```json
{
  "errors": [
    {
      "id": "req_abc123",
      "type": "https://apix.floqast.app/errors/not_found",
      "title": "Not Found",
      "status": 404,
      "code": "resource_not_found",
      "detail": "User 64abc123 was not found in this tenant.",
      "instance": "/v2/core/users/64abc123"
    }
  ]
}
```

| Field | Description |
|  --- | --- |
| `id` | Request trace ID — include this when contacting support. |
| `code` | Machine-readable error code (e.g. `resource_not_found`, `invalid_parameter`). |
| `detail` | Human-readable, occurrence-specific explanation. |
| `param` | The field or query parameter that caused the error (when applicable). |


## Rate Limiting

The API enforces rate limits. When exceeded, the response is `429 Too Many Requests` with a `Retry-After` header indicating seconds to wait before retrying.