API Forwarder

The 4C:me Safe AI Platform provides an API forwarder that allows external applications to interact with the platform's services using API keys. This enables programmatic access to agents, chat, transcription, and more — without requiring a browser session.

Overview

The API forwarder acts as a secure gateway between external applications and the platform's internal services. It validates API keys, enforces permission scopes, and forwards authenticated requests to the appropriate backend service.

Key features:

• API key authentication — Use API keys instead of browser-based SSO
• Granular scopes — Control exactly which capabilities each key can access
• Expiration policies — Keys can be configured to expire after a set period
• Audit trail — Track when keys were created and last used

Managing API Keys

Navigate to Settings > API Keys to view and manage your API keys. Each key displays:

• Name — A label you assigned when creating the key
• Key prefix — The first characters of the key (e.g. afk_4d850c05...)
• Expiration date — When the key will stop working
• Last used — When the key was last used to make a request
• Created date — When the key was generated
• Scopes — The permission scopes assigned to the key

Creating an API Key

1. Click + Create Key on the API Keys page
2. Enter a descriptive Name (e.g. "Production Bot")
3. Select the Permissions the key should have (see Scopes below)
4. Choose an Expiration period (default: 30 days)
5. Click Create Key

warning

The full API key is only shown once at creation time. Copy and store it securely — it cannot be retrieved later.

Deleting an API Key

Click the trash icon next to any key to revoke it immediately. Revoked keys can no longer authenticate requests.

Authentication

Include the API key in the x-api-key header of every request:

curl -X POST https://your-platform-url/api/v1/completions \
  -H "x-api-key: afk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Scopes

Each API key is assigned one or more scopes that determine which endpoints it can access. Scopes are organized into two groups:

Agents

Scopes for managing knowledge agents — the AI personas backed by indexed documents and custom configurations.

Scope	Description
View Agents	Read-only access to agents, their status, categories, search, and indexed documents
Edit Agents	Modify existing agents, trigger indexing, and manage agent documents
Create Agents	Create new agents
Delete Agents	Remove agents
Manage All Agents	Full agent access that bypasses user-group restrictions. Includes all of the above

Tools

Scopes for using the platform's AI tools.

Scope	Description
Use Chat	Access the chat completion engine, conversation history, projects, and related features
Use Transcripts	Access audio transcription and file upload

---

Endpoints by Scope

All endpoints are accessible through the API forwarder base URL. The forwarder routes requests to the appropriate internal service.

View Agents

Read-only access to agents and their data.

Agents

Method	Endpoint	Description
GET	/agents	List agents (supports ?page, ?pageSize, ?search, ?categories, ?isPublic, ?sortBy, ?sortDirection)
GET	/agents/{agentId}	Get agent details and configuration
GET	/agents/indexed-count	Get total count of indexed agents

Agent Indexing Status

Method	Endpoint	Description
GET	/agents/{agentId}/status	Get current indexing status
GET	/indexing-tracking/{agentId}/progress	Get indexing progress
GET	/indexing-tracking/{agentId}/results	Get final indexing results
GET	/indexing-tracking/{agentId}/status	Get indexing session status

Agent Search

Method	Endpoint	Description
POST	/agents/{agentId}/search	Search documents in an agent's index
POST	/search/{agentId}/semantic-search	Semantic search
POST	/search/{agentId}/vector-search	Vector search (supports ?topK)
POST	/search/{agentId}/hybrid-search	Hybrid search combining multiple strategies
POST	/search/{agentId}/iterative-hybrid-search	Iterative hybrid search with LLM judge (supports ?maxRetries)
POST	/search/{agentId}/enhanced-multipart-search	File-processing RAG search (multipart/form-data)
POST	/search/{agentId}/hyde-search	HyDE-enhanced search (supports ?method=single|multiple|reverse|adaptive)

Categories

Method	Endpoint	Description
GET	/categories	List all agent categories
GET	/categories/{id}	Get a specific category

Files & Documents

Method	Endpoint	Description
GET	/files/download/{blobPath}	Download a processed file
GET	/files/agents/{agentId}/document-counts	Get document counts for an agent

Template Documents

Method	Endpoint	Description
GET	/api/template-documents/{templateId}	Get a specific template document
GET	/api/template-documents/agent/{agentId}	Get all templates for an agent
GET	/api/template-documents/agent/{agentId}/prompt/{promptText}	Get template for a specific prompt
GET	/api/template-documents/processing/{processingId}	Get template processing status
GET	/api/template-documents/processing/{processingId}/stream	Stream processing status (SSE)
GET	/api/template-documents/processing/agent/{agentId}/prompt/{promptIndex}	Get processing status by prompt index

---

Edit Agents

Modify existing agents and their resources. Also includes all View Agents endpoints.

Agent Configuration

Method	Endpoint	Description
PUT	/agents/{agentId}	Update agent configuration

Indexing

Method	Endpoint	Description
POST	/agents/{agentId}/index-all	Trigger bulk indexing (supports ?stream=true for SSE progress)
POST	/agents/{agentId}/documents/delete	Delete documents from an agent's index
POST	/indexing-tracking/{agentId}/initialize	Initialize an indexing session
PUT	/indexing-tracking/{agentId}/file-result	Update a file processing result
DELETE	/indexing-tracking/{agentId}/reset	Reset indexing status
DELETE	/indexing-tracking/{agentId}/files	Delete file collection
POST	/indexing-tracking/{agentId}/cancel	Cancel an active indexing session
POST	/indexing-tracking/cleanup-stuck-sessions	Clean up abandoned indexing sessions

File Processing

Method	Endpoint	Description
POST	/files/process	Process uploaded files (multipart/form-data)
POST	/files/process-content	Process and extract file content (multipart/form-data)
POST	/files/circuit-breaker/reset	Reset image processing circuit breaker

Categories

Method	Endpoint	Description
POST	/categories	Create a new category
PUT	/categories/{id}	Update a category
DELETE	/categories/{id}	Delete a category

Template Documents

Method	Endpoint	Description
POST	/api/template-documents	Create a template document
POST	/api/template-documents/from-buffer	Create template from uploaded file (multipart/form-data)
POST	/api/template-documents/cleanup-orphaned	Clean up orphaned template references
POST	/api/template-documents/processing/agent/{agentId}/prompt/{promptIndex}/cancel	Cancel template processing
PUT	/api/template-documents/agent/{agentId}/prompt/{promptText}	Replace a template document
DELETE	/api/template-documents/{templateId}	Delete a template document
DELETE	/api/template-documents/agent/{agentId}/prompt/{promptIndex}	Remove template from a prompt
PATCH	/api/template-documents/agent/{agentId}/prompt/{promptIndex}/text	Update prompt text

---

Create Agents

Create new agents. Also includes all View Agents endpoints.

Method	Endpoint	Description
POST	/agents	Create a new agent

---

Delete Agents

Delete agents. Also includes all View Agents endpoints.

Method	Endpoint	Description
DELETE	/agents/{agentId}	Delete an agent

---

Manage All Agents

Grants full access to all agent endpoints listed above (View, Edit, Create, Delete), and additionally bypasses user-group restrictions. With this scope, the API key can manage agents regardless of which user groups they are assigned to.

---

Use Chat

Access the chat completion engine, conversation history, and related features.

Completions

Method	Endpoint	Description
POST	/api/v1/completions	Send a chat completion request (JSON body)
POST	/api/v1/completions/multipart	Send a completion with file attachments (multipart/form-data)

Messages

Method	Endpoint	Description
POST	/api/v1/messages	Create a new message
POST	/api/v1/messages/generate-title	Generate a conversation title from chat history
GET	/api/v1/messages/conversation-title/{conversationId}	Get a conversation's title
PUT	/api/v1/conversations/{conversationId}/messages/latest-assistant/rag-documents	Update RAG documents on the latest assistant message

Models

Method	Endpoint	Description
GET	/api/v1/models	List available AI models

Prompt Templates

Method	Endpoint	Description
GET	/api/v1/templates	List prompt templates
POST	/api/v1/templates	Create a prompt template
PUT	/api/v1/templates/{templateId}	Update a prompt template
DELETE	/api/v1/templates/{templateId}	Delete a prompt template

Categories (Chat)

Method	Endpoint	Description
GET	/api/v1/categories	List prompt template categories
POST	/api/v1/categories	Create a category
PUT	/api/v1/categories/{categoryId}	Update a category
DELETE	/api/v1/categories/{categoryId}	Delete a category
POST	/api/v1/categories/reorder	Reorder categories

Conversations

Method	Endpoint	Description
POST	/api/v1/history/conversations/	Create a new conversation
PATCH	/api/v1/history/conversations/{conversationId}/edit	Edit conversation name or pinned status
PATCH	/api/v1/history/conversations/{conversationId}/delete	Delete a conversation
PATCH	/api/v1/history/conversations/{conversationId}/read	Mark conversation as read
GET	/api/v1/history/conversations/user/{userId}	List all conversations for a user
GET	/api/v1/history/conversations/user/{userId}/recent	List recent conversations (supports ?limit, ?page, ?projectId)

Chat Messages (History)

Method	Endpoint	Description
POST	/api/v1/history/chat/messages	Store a chat message
GET	/api/v1/history/chat/messages/{conversationId}	Get messages for a conversation (supports ?limit, ?beforeId)
PATCH	/api/v1/history/chat/messages/{id}	Update a message
DELETE	/api/v1/history/chat/messages/last	Delete the last message in a conversation
GET	/api/v1/history/chat/messages/user-images	Get user images from messages

Projects

Method	Endpoint	Description
POST	/api/v1/projects/	Create a new project
PATCH	/api/v1/projects/{projectId}	Update a project
DELETE	/api/v1/projects/{projectId}	Delete a project
GET	/api/v1/projects/user/{userId}	List projects for a user
PATCH	/api/v1/projects/{projectId}/conversations/{conversationId}/link	Link a conversation to a project
PATCH	/api/v1/projects/conversations/{conversationId}/unlink	Unlink a conversation from a project
GET	/api/v1/projects/{projectId}/conversations/{userId}	Get conversations linked to a project

Presets

Method	Endpoint	Description
POST	/api/v1/preset	Create a new preset
PATCH	/api/v1/preset/{presetId}	Update a preset
DELETE	/api/v1/preset/{presetId}	Delete a preset
GET	/api/v1/preset/user/{userId}	List presets for a user

User Settings

Method	Endpoint	Description
POST	/api/v1/user-settings/get	Get user settings
POST	/api/v1/user-settings	Create user settings
PUT	/api/v1/user-settings	Update user settings
DELETE	/api/v1/user-settings	Delete user settings

Files

Method	Endpoint	Description
POST	/api/v1/files/process	Process uploaded files
POST	/api/v1/upload/image	Upload an image (multipart/form-data)
GET	/api/v1/upload/image/download	Download an image (supports ?url, ?filename)

Image Generation

Method	Endpoint	Description
POST	/api/v1/generate/image	Generate images from text prompts

Prompt Enhancer

Method	Endpoint	Description
POST	/api/v1/prompt-enhancer/enhance	Enhance a prompt
POST	/api/v1/prompt-enhancer/basic-enhance	Basic prompt enhancement
GET	/api/v1/prompt-enhancer/skills	List available enhancement skills

Tasks

Method	Endpoint	Description
GET	/api/v1/tasks/active	Get active tasks (supports ?conversationId, ?userId)
GET	/api/v1/tasks/active/user	Get active tasks by user
POST	/api/v1/tasks/pre-create	Pre-create a task
POST	/api/v1/tasks/{taskId}/acknowledge	Acknowledge a task
POST	/api/v1/tasks/{taskId}/stop	Stop a task

---

Use Transcripts

Access audio transcription features.

Transcription

Method	Endpoint	Description
POST	/api/transcription	Submit a transcription job (body: BlobUrl or BlobUrls)
GET	/api/transcription/{jobId}/status	Get transcription job status
GET	/api/transcription/{jobId}/result	Download transcription results
GET	/api/transcription/previous	List previous transcriptions for the user
GET	/api/transcription/{jobId}/details	Get full transcription details (supports ?resultId)
PATCH	/api/transcription/{jobId}/details	Update transcription details (supports ?resultId)
DELETE	/api/transcription/{jobId}	Delete a transcription (supports ?resultId)

File Upload

Method	Endpoint	Description
POST	/api/upload/upload	Upload an audio file for transcription (multipart/form-data)

Projects (Transcription)

Method	Endpoint	Description
PATCH	/api/v1/projects/{projectId}/transcriptions/{jobId}/link	Link a transcription to a project
PATCH	/api/v1/projects/transcriptions/{jobId}/unlink	Unlink a transcription from a project