> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# API Usage Guide

> Learn how to authenticate, find required IDs, and call Alephant APIs

This guide covers the common parameters you need before calling Alephant APIs: authentication tokens, workspace IDs, resource IDs, date ranges, and scoped analytics filters.

## Base URL

Use the API host shown in the API Reference for your environment. Examples in this guide use:

```bash
https://alephant.io
```

## Authentication

Most workspace APIs require both an `Authorization` header and an `X-Workspace-Id` header.

```bash
Authorization: Bearer <token>
X-Workspace-Id: <workspace-id>
```

Supported token types depend on the route:

| Token type                  | Best for                              | Notes                                                                       |
| --------------------------- | ------------------------------------- | --------------------------------------------------------------------------- |
| User JWT                    | Dashboard and first-party UI sessions | Usually obtained through login flows.                                       |
| Personal Access Token (PAT) | Server-to-server workspace automation | Use `Bearer pat_...`; route scopes may require `read`, `write`, or `admin`. |
| Virtual Key                 | Key-scoped cockpit and MCP workflows  | Use Cockpit routes to discover scope before calling workspace APIs.         |

PAT management routes under `/api/v1/pats` are JWT-only. A PAT cannot manage other PATs.

## Finding Required IDs

Many APIs need IDs that come from your workspace. Use the SaaS API to list resources, then pass the returned IDs into analytics or management APIs.

| ID             | How to get it                                                                             | Used by                                                 |
| -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `workspaceId`  | `GET /api/v1/workspaces`, or `GET /api/v1/cockpit/scope` when starting from a virtual key | `X-Workspace-Id`, most workspace APIs                   |
| `agentId`      | `GET /api/v1/agents`                                                                      | Agent analytics and scoped usage filters                |
| `memberId`     | `GET /api/v1/members`                                                                     | Member analytics and scoped usage filters               |
| `departmentId` | `GET /api/v1/departments`                                                                 | Department analytics, budgets, and scoped usage filters |
| `masterKeyId`  | `GET /api/v1/master-keys`                                                                 | Master key analytics and key management                 |

If your integration only has a virtual key (`vk-...`), first call:

```bash
curl https://alephant.io/api/v1/cockpit/scope \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY"
```

The response can include `workspace.id`, `virtual_key.id`, and an optional bound `entity.id` plus `entity.department_id`. Use `workspace.id` as `X-Workspace-Id` for workspace-scoped APIs.

## Tracking Gateway Requests

When sending model traffic through Alephant Gateway, attach agent and run context so logs and analytics can group requests correctly.

| Header                | Scope                                   |
| --------------------- | --------------------------------------- |
| `Alephant-Agent-Id`   | Stable Agent ID from Alephant           |
| `Alephant-Run-Id`     | One task execution                      |
| `alephant-session-id` | Conversation, workflow, or job grouping |
| `x-request-id`        | One gateway request                     |

Example:

```bash
curl https://ai.alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
  -H "alephant-session-id: sess_customer_123_support_20260609" \
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Summarize this ticket." }
    ]
  }'
```

See [Agent IDs And Run IDs](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds) for full usage patterns.

## Date Ranges

Analytics endpoints commonly accept `dateFrom` and `dateTo` as `YYYY-MM-DD`.

```text
dateFrom=2026-05-01
dateTo=2026-05-09
```

For `/api/v1/analytics/*` routes in the SaaS API:

* If you send either `dateFrom` or `dateTo`, send both.
* If you omit both, the service uses the current billing period where supported.
* `dateFrom` must not be after `dateTo`.

Some lower-level Analytics API endpoints use `start` and `end` instead. Check the endpoint reference before mixing parameter names.

## Scoped Analytics Filters

`GET /api/v1/analytics/usage` supports scoped usage series. Set at most one of:

* `agentId`
* `memberId`
* `departmentId`

Example: usage for one agent.

```bash
curl "https://alephant.io/api/v1/analytics/usage?dateFrom=2026-05-01&dateTo=2026-05-09&agentId=$AGENT_ID" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

If more than one scope is sent, the API returns a bad request.

## Common Calls

Workspace analytics overview:

```bash
curl "https://alephant.io/api/v1/analytics/overview?dateFrom=2026-05-01&dateTo=2026-05-09" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

Cost breakdown:

```bash
curl "https://alephant.io/api/v1/analytics/costs?dateFrom=2026-05-01&dateTo=2026-05-09" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

Usage history:

```bash
curl "https://alephant.io/api/v1/analytics/usage-history?months=12" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

## SaaS API vs Analytics API

Use the SaaS API (`/api/v1/...`) for product workflows, workspace management, and dashboard-oriented analytics.

Use the Analytics API (`/v1/analytics/...`) for lower-level telemetry and collector-backed analytics. These endpoints generally require the same workspace context, but their parameter names and response shapes can be more collector-specific.

When building an external integration, start with the SaaS API unless you specifically need a collector-level analytics endpoint.