REST API

Name: TaskForceAI
Author: TaskForceAI

Complete REST API reference with authentication, endpoints, rate limits, and response formats.

Getting Started

The TaskForceAI API is accessible through our web dashboard. Follow these steps:

Create Account

Get API Key

Navigate to Settings → API Keys

Start Building

Make requests to the API

Authentication

All API requests require an x-api-key header:

x-api-key: your-api-key-here

Base URL

https://taskforceai.chat/api

Local Development

Build and test your integration without an API key using mock mode:

Option 1: SDK Mock Mode

Both SDKs support a mock mode that simulates API responses locally:

// TypeScript
const client = new TaskForceAI({ mockMode: true });

# Python
client = TaskForceAIClient(mock_mode=True)

Option 2: Local Mock Server

Run a local mock server using the TaskForceAI CLI:

/mock

This starts a local server at http://localhost:4321/api/developer that mirrors the production API. Point your SDK at this URL:

// TypeScript
const client = new TaskForceAI({
  apiKey: 'test',
  baseUrl: 'http://localhost:4321/api/developer'
});

# Python
client = TaskForceAIClient(
    api_key="test",
    base_url="http://localhost:4321/api/developer"
)

Request Headers

Include these headers in all requests:

x-api-key: your-api-key-here
Content-Type: application/json

Endpoints

POST/api/developer/run

Submit a task for multi-agent orchestration.

Request Body:

{
  "prompt": "What is the capital of France?",
  "options": {
    "modelId": "xai/grok-4.1",
    "silent": false,
    "mock": false
  }
}

Options:
• modelId: (String) ID of the AI model to use (e.g., xai/grok-4.1). See /api/v1/models for available IDs.
• silent: (Boolean) If true, suppresses detailed logging.
• mock: (Boolean) If true, returns a simulated response for testing.

Response:

{
  "taskId": "task_abc123",
  "status": "processing"
}

GET/api/v1/models

Get a list of available AI models and their capabilities.

{
  "options": [
    { "id": "xai/grok-4.1-fast-reasoning", "label": "Grok 4.1 Fast" },
    { "id": "google/gemini-3-pro-preview", "label": "Gemini 3 Pro" }
  ],
  "defaultModelId": "xai/grok-4.1-fast-reasoning"
}

GET/api/developer/status/[taskId]

Check the status of a submitted task.

Response:

{
  "taskId": "task_abc123",
  "status": "processing | completed | failed"
}

GET/api/developer/results/[taskId]

Get the final result of a completed task.

Response:

{
  "taskId": "task_abc123",
  "status": "completed",
  "result": "The capital of France is Paris.",
  "agents": [...],
  "metadata": {...}
}

Threads & Runs (Stateful API)

Manage persistent conversations using Threads. This allows for multi-turn interactions and state management directly on the TaskForceAI platform.

POST/api/v1/developer/threads

Initialize a new conversation thread.

{
  "title": "Project Research"
}

POST/api/v1/developer/threads/[threadId]/runs

Trigger an orchestration run within an existing thread.

{
  "prompt": "What are the latest trends in AI?",
  "modelId": "xai/grok-4.1",
  "stream": true
}

Real-time Streaming (SSE)

Watch the multi-agent orchestrator think in real-time using Server-Sent Events.

GET/api/v1/stream/[taskId]

Subscribe to real-time events from the orchestrator.

// Example Event (data: ...)
{
  "type": "status",
  "agentStatuses": [...],
  "toolEvents": [...]
}

Files (Attachments)

Upload documents (PDF, CSV, TXT) that agents can analyze during a run.

POST/api/v1/files

Upload a file via multipart/form-data.

{
  "id": "file-12345",
  "filename": "report.pdf",
  "purpose": "assistants"
}

Rate Limits

Rate limits vary by plan tier:

Tier	Requests/Month	Rate Limit	Price
Free	8	2/week	$0
Pro	~1,500	2/hour	$28/mo
Super	~15,000	20/hour	$280/mo

Rate limit information is included in response headers: x-ratelimit-remaining and x-ratelimit-reset.

Response Headers

request-id

Unique identifier for debugging and support

x-ratelimit-remaining

Number of requests remaining in current window

x-ratelimit-reset

Unix timestamp when the rate limit resets

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Task ID does not exist
413	Request Too Large - Exceeds size limit
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Contact support

REST API

Getting Started

Create Account

Get API Key

Start Building

Authentication

Base URL

Local Development

Option 1: SDK Mock Mode

Option 2: Local Mock Server

Request Headers

Endpoints

Request Body:

Response:

Response:

Response:

Threads & Runs (Stateful API)

Real-time Streaming (SSE)

Files (Attachments)

Rate Limits

Response Headers

Error Codes

Next Steps