Skip to content

API Overview

The fifthelement.ai API provides programmatic access to platform features including chat agents, document management, and repository operations.

Base URL

https://PLATFORM-URL-PLACEHOLDER/v1/api

Authentication

All API requests require authentication using API keys. Create an API key from Settings > Security & Access > API Keys in the platform.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories

API Key Types

Type Identity Header
User API Key Personal — inherits your full user permissions Authorization: Bearer <token>
Workspace API Key System-level — paired with a dedicated Service Account; independent of any individual user Authorization: Bearer <token> + optional x-user-identifier

See API Keys for details on generating both types.

Acting on Behalf of an Identity (x-user-identifier)

The current interactive API schema documents an optional x-user-identifier header for Workspace API Keys. It resolves the request identity as follows; this is identity selection, not merely a logging label:

x-user-identifier value Resolved Identity
Accepted member email in the token’s workspace Runs as that matched workspace member
Service Account UUID Runs explicitly as the service account
(omitted / unmatched) Falls back to the workspace system user 
curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/your-agent" \
  -H "Authorization: Bearer YOUR_WORKSPACE_API_TOKEN" \
  -H "x-user-identifier: alice@example.com" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Header Scope

x-user-identifier is honoured only by Workspace API Keys. It is ignored when authenticating with User API Keys or JWT-based session auth.

Creating an API Token

Endpoint: POST /user-api-tokens

Generate an API token with a custom name for identification:

curl -X POST https://PLATFORM-URL-PLACEHOLDER/v1/api/user-api-tokens \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Token"}'

API Categories

The fifthelement.ai API is organized into the following categories:

Rate Limits

Confirm the limits that apply to your deployment and integration before planning request volume. Handle HTTP 429 without a tight retry loop. If a response provides a Retry-After value, respect it; otherwise use bounded backoff and stop after your configured retry budget. Do not assume every endpoint returns rate-limit headers.

Response Format

The following JSON examples illustrate a response envelope. Consult the endpoint schema for its exact response; streaming responses require the handling described in the Chat API.

Success Response

{
  "data": {},
  "error": null
}

Error Response

{
  "data": null,
  "error": {
    "name": "ValidationError",
    "message": "Invalid request parameters",
    "details": {}
  }
}

Error Codes

Status Code Description
200 Success - Request completed successfully
400 Bad Request - Invalid input data or malformed request
401 Unauthorized - Authentication required or invalid credentials
403 Forbidden - Insufficient permissions for this resource
404 Not Found - Resource does not exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server-side error occurred

Interactive Documentation

For interactive API testing and detailed schemas, visit our Swagger UI:

https://PLATFORM-URL-PLACEHOLDER/v1/documentation

Quick Start Example

Here's a complete example showing how to chat with an agent:

# 1. Get your API token from Settings > API Keys

# 2. Send a message to an agent
curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/your-agent-slug" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how can you help me?",
    "stream": false,
    "conversationId": null
  }'