API Usage Guide | Alephant Documentation

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:

$ https://alephant.io

Authentication

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

$ 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:

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

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.

$ 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:

$ 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:

$ 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:

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