> ## Documentation Index
> Fetch the complete documentation index at: https://v4-docs.alfaone.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the AlfaOne Public API

## Base URL

All API requests should be made to:

```
https://alfaone.app/api/v1
```

## Authentication

All endpoints require an API key passed in the `x-api-key` header:

```bash theme={null}
curl -X GET "https://alfaone.app/api/v1/assessments" \
  -H "x-api-key: ak_live_your_api_key_here"
```

See the [Authentication](/authentication) page for more details.

## Response Format

All responses are returned in JSON format. Successful responses will include the requested data, while error responses will include an `error` field with a descriptive message.

### Success Response

```json theme={null}
{
  "assessments": [
    {
      "id": "uuid",
      "name": "Assessment Name"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

### Error Response

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

## HTTP Status Codes

| Status Code | Description                                             |
| ----------- | ------------------------------------------------------- |
| `200`       | Success - Request completed successfully                |
| `201`       | Created - Resource was created successfully             |
| `400`       | Bad Request - Invalid or missing request parameters     |
| `401`       | Unauthorized - Invalid or missing API key               |
| `404`       | Not Found - The requested resource doesn't exist        |
| `409`       | Conflict - The resource already exists                  |
| `429`       | Too Many Requests - Rate limit exceeded                 |
| `500`       | Internal Server Error - Something went wrong on our end |

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Assessments" icon="clipboard-list" href="/api-reference/assessments/list-assessments">
    List, retrieve, and view questions for assessments
  </Card>

  <Card title="Members" icon="users" href="/api-reference/members/list-members">
    Access organization member information
  </Card>

  <Card title="Invites" icon="envelope" href="/api-reference/invites/list-invites">
    Send assessment invites and track their status
  </Card>

  <Card title="Tags" icon="tag" href="/api-reference/tags/list-tags">
    Create, update, and manage organization tags
  </Card>
</CardGroup>

## Pagination

All list endpoints support pagination through query parameters. Results are returned alongside a `pagination` metadata object.

### Query Parameters

| Parameter | Type    | Default  | Description                                             |
| --------- | ------- | -------- | ------------------------------------------------------- |
| `page`    | integer | `1`      | Page number (1-indexed)                                 |
| `limit`   | integer | `20`     | Items per page (min 1, max 100)                         |
| `sort`    | string  | *varies* | Field to sort by (see each endpoint for allowed values) |
| `order`   | string  | `desc`   | Sort direction: `asc` or `desc`                         |

### Example Request

```bash theme={null}
curl -X GET "https://alfaone.app/api/v1/assessments?page=2&limit=10&sort=name&order=asc" \
  -H "x-api-key: ak_live_your_api_key_here"
```

### Paginated Response

Every list response includes a `pagination` object alongside the resource array:

```json theme={null}
{
  "assessments": [
    {
      "id": "uuid",
      "name": "Assessment Name"
    }
  ],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 87,
    "totalPages": 9
  }
}
```

| Field        | Description                                |
| ------------ | ------------------------------------------ |
| `page`       | The current page number                    |
| `limit`      | The number of items per page               |
| `total`      | The total number of items across all pages |
| `totalPages` | The total number of pages                  |

## Versioning

The API is versioned via the URL path (`/api/v1/`). When breaking changes are introduced, a new version will be released while maintaining support for previous versions during a deprecation period.