API Documentation
Explore our API to integrate your applications with Alkimi.
API in Alpha
Getting Started
Authentication
All requests to the Alkimi API must be authenticated using an API token. Organization administrators generate and manage API keys (personal keys, or keys owned by a service account) under Organization Settings > API Keys. Include your token in the
Authorization
header using the
Bearer
scheme.
Authorization: Bearer YOUR_API_TOKENRequest Headers
In addition to the Authorization header, the API supports the following headers to set request context:
| Header | Description | Required |
|---|---|---|
| x-timezone | Sets the timezone for the request (e.g., "America/New_York"). Defaults to UTC if not provided. | Optional |
| x-organization-id | The public ID of the organization to scope the request to. If not provided, the system attempts to infer it from the user's default or available organizations. | Optional |
| x-workspace-id | The public ID of the workspace to scope the request to. Required by every workspace-scoped resource route (agents, chats, knowledge collections, shares); the request fails with 400 if it is missing or names an archived workspace. |
Required for workspace resources |
Making a Request
All API endpoints are versioned. The current version is
v1
, which must be included in the URL path.
Here’s a quick example using
curl
to fetch your user details. Replace
YOUR_API_TOKEN
with your actual API key.
curl -X GET https://api.alkimi.ai/v1/users/me \
-H "Authorization: Bearer YOUR_API_TOKEN"Rate Limiting
The Alkimi API enforces rate limits to ensure system stability and fair usage. Limits are applied at two levels:
Global Limits
Applies to all requests across the entire API.
- 6,000 / 1m per IP
- 600 / 1m per User
Endpoint Limits
Specific overrides for sensitive or resource-heavy actions.
Refer to individual endpoint documentation for specific limits (e.g., Auth, Knowledge ingestion, AI generation).
When a limit is exceeded, the API returns a 429 Too Many Requests response.
The following headers are included in every response to help you track your current usage:
| Header | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of requests allowed in the current window. |
| X-RateLimit-Remaining | The number of requests remaining in the current window. |
| X-RateLimit-Reset | The time at which the current rate limit window resets (ISO 8601). |
| Retry-After | Included only on 429 errors. The number of seconds to wait before retrying. |
Errors
The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses are returned in JSON format with a descriptive message.
| Code | Description |
|---|---|
| 400 | Bad Request - The request was invalid or cannot be otherwise served. Check for missing parameters or invalid data formats. |
| 401 | Unauthorized - Authentication failed or was not provided. Check your API token. |
| 403 | Forbidden - You do not have permission to access this resource, even with a valid token. |
| 404 | Not Found - The requested resource could not be found. |
| 429 | Too Many Requests - You have exceeded the rate limit for this endpoint. See the specific endpoint documentation for rate limit details. |
| 500 | Internal Server Error - Something went wrong on our end. Please try again later. |
Permissions Reference
Below is a reference list of all permissions used in the API. These can be assigned to users via Roles or checked when creating API keys.
| Permission | Description |
|---|---|
| Agent Permissions | |
| agent:audit | View agent audit trail and activity history. |
| agent:chat | Interact with the agent via chat and generate responses. |
| agent:delete | Delete the agent. Only available to the agent owner. |
| agent:manage | Update agent settings and configuration. |
| agent:roles:manage | Manage user access roles and permissions for the agent. |
| agent:read | View agent details, configuration, and usage statistics. |
| Collection Permissions | |
| collection:audit | View collection audit trail and activity history. |
| collection:delete | Delete the collection. Only available to the collection owner. |
| collection:read | View collection details, settings, and list items. |
| collection:use | Use the collection as a knowledge source in agents. |
| collection:manage | Update collection settings and configuration. |
| collection:items:manage | Add, update, remove, or move knowledge items within the collection. |
| collection:roles:manage | Manage user access roles and permissions for the collection. |
| Org Permissions | |
| org:apikeys:manage | Create, update, and delete API keys for the organization. |
| org:apikeys:view | List and view details of organization API keys. |
| org:audit:view | View the organization audit log. |
| org:billing:manage | Manage subscription plans, payment methods, and view billing history. |
| org:members:manage | Invite new members, update roles, and remove members from the organization. |
| org:external:manage | Invite and manage external members who use their own subscription for credits on private agents. |
| org:roles:manage | Create, edit, and delete organization role definitions. Restricted to the admin role. |
| org:delete | Delete the organization. Restricted to the admin role. |
| org:admin | Org-wide resource visibility (show all workspaces, agents, and collections), self-grant access, auto-join management, and organization model configuration (enable/disable models and bulk migration). Restricted to the admin role. |
| org:settings:manage | Update organization name, profile, security settings, policies, verified domains, and integrations. View organization model configuration (modifying which models are enabled requires org:admin). |
| org:studio:view | Access the Content Studio page. |
| org:templates:manage | Create and manage organization-level agent templates. |
| org:workspaces:create | Create new workspaces within the organization. |
| Workspace Permissions | |
| workspace:agents:create | Create new agents within the workspace. |
| workspace:collections:create | Create new knowledge collections within the workspace. |
| workspace:assignments:view | View assignments within the workspace. |
| workspace:assignments:manage | Create, update, and delete assignments within the workspace. |
| workspace:members:manage | Add, remove, and update workspace member roles. |
| workspace:roles:manage | Create, edit, and delete workspace role definitions. |
| workspace:settings:manage | Update workspace settings and configuration. |
| workspace:audit:view | View the workspace audit trail and activity history. |
| workspace:delete | Delete the workspace. Only available to the workspace owner. |
Users
https://api.alkimi.ai/v1/usersOrganizations
https://api.alkimi.ai/v1/organizationsInvitations
https://api.alkimi.ai/v1/invitationsAgents
https://api.alkimi.ai/v1/agentsChats
https://api.alkimi.ai/v1/chatsMessages
https://api.alkimi.ai/v1/chats/:chatId/messagesKnowledge
https://api.alkimi.ai/v1/knowledgePermissions
https://api.alkimi.ai/v1/permissions