> 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 full documentation content, see https://developers.alephant.io/llms-full.txt.

# 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.

## 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.