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

# API Overview

> The OpenIndex HTTP API — endpoints, authentication, and conventions.

The OpenIndex HTTP API lets you create and manage work items, domains, workflows, calendar sources, email infrastructure, and more. You can access it from any HTTP client, including the `oi` CLI and the web application.

## Base URL

Your API base URL is the URL of your OpenIndex deployment. If you're using the hosted service:

```
https://app.openindex.dev
```

For self-hosted deployments, use your configured site URL. All OpenIndex HTTP routes (`/browse`, `/domains`, `/calendar-sources`, etc.) are served from this base URL. The `oi` CLI resolves this automatically from your profile's `--app-url`.

## Authentication

All API requests (except `/health`) require a Bearer token in the `Authorization` header:

```
Authorization: Bearer <your-pat>
```

Personal Access Tokens (PATs) are the primary authentication method. See [API Authentication](/api/authentication) for how to create and manage tokens.

## Content type

Send all request bodies as JSON with the `Content-Type` header:

```
Content-Type: application/json
```

## Work item keys

Work items use domain-scoped keys in the format `DOMAINKEY-123`. Sub-tasks inherit the parent task key with a sequence suffix:

| Type     | Key format | Example    |
| -------- | ---------- | ---------- |
| Project  | `KEY-N`    | `OPS-1`    |
| Task     | `KEY-N`    | `OPS-42`   |
| Sub-task | `KEY-N.N`  | `OPS-42.1` |

Use these keys as path parameters in work item endpoints (e.g. `GET /browse/OPS-42`).

## Endpoint groups

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Personal Access Tokens and invite claiming.
  </Card>

  <Card title="Work Items" icon="list-check" href="/api/work-items">
    Create, read, update, and manage work items.
  </Card>

  <Card title="Workflows" icon="code-branch" href="/api/workflows">
    Workflow definitions and custom fields.
  </Card>

  <Card title="Domains" icon="building" href="/api/domains">
    Domains and membership management.
  </Card>

  <Card title="Calendar" icon="calendar" href="/api/calendar">
    ICS calendar sources and events.
  </Card>

  <Card title="Email" icon="envelope" href="/api/email">
    Mailboxes, routing rules, and email infrastructure.
  </Card>

  <Card title="Audit" icon="scroll" href="/api/audit">
    Audit logs and operational statistics.
  </Card>
</CardGroup>

## Health check

```bash theme={null}
GET /health
```

Returns `200 OK` with no authentication required. Use this to verify your deployment is reachable.

## Current user

```bash theme={null}
GET /me
Authorization: Bearer <your-pat>
```

Returns the profile of the authenticated user.

## Operational stats

```bash theme={null}
GET /stats
Authorization: Bearer <your-pat>
```

Returns operational statistics for the instance, including work item counts, active workflows, and recent activity.

## HTTP status codes

| Code               | Meaning                                                                  |
| ------------------ | ------------------------------------------------------------------------ |
| `200 OK`           | Request succeeded.                                                       |
| `201 Created`      | Resource created successfully.                                           |
| `400 Bad Request`  | Invalid request body or parameters. Check the error message for details. |
| `401 Unauthorized` | Missing or invalid Bearer token.                                         |
| `403 Forbidden`    | Token does not have the required scope for this operation.               |
| `404 Not Found`    | Resource does not exist or is not accessible with your credentials.      |