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)

Workspace API Keys support an optional x-user-identifier header that lets a single integration attribute actions to a specific principal:

x-user-identifier value Resolved Identity
Workspace member email Runs as that workspace member with their permissions
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

API requests are rate-limited based on your account tier:

  • Standard: 1,000 requests per hour
  • Premium: 10,000 requests per hour
  • Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Response Format

All API responses follow a consistent format:

Success Response

{
  "data": {
    // 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
  }'