Alkimi AI Logo Alkimi AI

API Documentation

Explore our API to integrate your applications with Alkimi.

Getting Started

Authentication

All requests to the Alkimi API must be authenticated using an API token. You can generate and manage your API tokens from your account settings. Include your token in the Authorization header using the Bearer scheme. 

Authorization: Bearer YOUR_API_TOKEN

Request 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

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/user \
-H "Authorization: Bearer YOUR_API_TOKEN"

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.
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:chat Interact with the agent via chat and generate responses.
agent:manage Update agent settings, configuration, and delete the agent.
agent:permissions:manage Manage user access roles and permissions for the agent.
agent:read View agent details, configuration, and usage statistics.
Collection Permissions
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:permissions:manage Manage user access roles and permissions for the collection.
Org Permissions
org:agents:create Create new agents within the organization.
org:agents:delete Delete any agent within the organization (Admin override).
org:apikeys:manage Create, update, and delete API keys for the organization.
org:apikeys:read List and view details of organization API keys.
org:billing:manage Manage subscription plans, payment methods, and view billing history.
org:collections:create Create new knowledge collections within the organization.
org:collections:delete Delete any collection within the organization (Admin override).
org:manage Update organization details and settings.
org:member Basic membership access to the organization.
org:members:manage Invite new members, update roles, and remove members from the organization.
org:members:read View the list of organization members and their roles.
Page Permissions
page:agents:view Access the Agents management page.
page:collections:view Access the Knowledge Collections management page.
page:settings:view Access the Organization Settings page.

Users

Base Path https://api.alkimi.com/v1/users

Organizations

Base Path https://api.alkimi.com/v1/organizations

Invitations

Base Path https://api.alkimi.com/v1/invitations

Agents

Base Path https://api.alkimi.com/v1/agents

Chats

Base Path https://api.alkimi.com/v1/chats

Shares

Base Path https://api.alkimi.com/v1/shares

Messages

Base Path https://api.alkimi.com/v1/chats/:chatId/messages

Knowledge

Base Path https://api.alkimi.com/v1/knowledge

Permissions

Base Path https://api.alkimi.com/v1/permissions

Schemas