> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/docs/overview/getting-started/api-usage-guide/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 X-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. > Learn how to authenticate, find required IDs, and call Alephant APIs