API Overview

TARX's REST API is the backend for the web app and is available for direct integration. This page covers the key endpoints, authentication, and patterns. For a fully interactive reference with request/response schemas, see the API Reference.

Base URL

https://api.tarx.io/api/v1

For local development:

http://localhost:8000/api/v1

Authentication

All API endpoints require a Platform API Key (sk-tarx-...). Include it as a Bearer token on every request:

Authorization: Bearer sk-tarx-xxxxxxxxxxxxxxxxxxxxx

Platform API Keys are permanent until deleted. Generate and manage them in Settings → Keys & Secrets → Platform API Keys.

# Verify your key works
curl https://api.tarx.io/api/v1/auth/me \
  -H "Authorization: Bearer sk-tarx-YOUR_KEY"

Generate a key

Go to Settings → Keys & Secrets → Platform API Keys → click New Key. The key value is shown once only — copy it immediately and store it in a secrets manager or environment variable.

Project Context

Most endpoints operate inside a project. TARX resolves the project from the request in this order:

Priority	Header	Value	Notes
1	(none)	—	Auto-resolved if you have exactly one project
2	`X-Project-Slug`	`my-project`	Your URL slug — scoped to your account, no collisions
3	`X-Project-ID`	UUID	Raw project ID from Settings → Projects

Recommended for scripts: use X-Project-Slug — it's the slug in your TARX URL (/{username}/{slug}/bridge) and it's human-readable.

X-Project-Slug: my-project

If you have multiple projects and send no header, the API returns 400 with a message asking you to specify one.

Key Endpoints

Authentication

Method	Endpoint	Description
`GET`	`/auth/me`	Get current user info (verify key is valid)

Users

Method	Endpoint	Description
`GET`	`/users/me`	Current user profile

LLM Keys (BYOK)

Project-scoped LLM keys, shared across project members. Listing is available to any member; adding/deleting requires the admin role. Requests are scoped by the project context header (X-Project-Slug / X-Project-ID).

Method	Endpoint	Description
`GET`	`/llm-keys`	List the current project's LLM keys (masked, no values)
`POST`	`/llm-keys`	Add a new LLM key to the project (admin only)
`DELETE`	`/llm-keys/{key_id}`	Delete a project LLM key (admin only)

Platform API Keys

Long-lived tokens (sk-tarx-...) for programmatic access — CI/CD, scripts, and external services. Personal to your account (not project-scoped); they authenticate as you and select a project via the context header.

Method	Endpoint	Description
`GET`	`/platform-keys`	List your platform API keys (no key values returned)
`POST`	`/platform-keys`	Create a new platform API key (plaintext returned once)
`DELETE`	`/platform-keys/{key_id}`	Delete a platform API key

Create key response (key plaintext is shown once only):

{
  "id": "key_abc123",
  "name": "CI Pipeline",
  "created_at": "2025-05-23T10:00:00Z",
  "key": "sk-tarx-a1b2c3d4e5f6..."
}

Projects

Method	Endpoint	Description
`GET`	`/projects`	List all projects you're a member of
`GET`	`/projects/{project_id}`	Get project details
`GET`	`/projects/{project_id}/members`	List project members

Agents

Method	Endpoint	Description
`GET`	`/agents`	List all agents in project
`POST`	`/agents`	Create an agent
`GET`	`/agents/{agent_id}`	Get agent details
`PUT`	`/agents/{agent_id}`	Update an agent
`DELETE`	`/agents/{agent_id}`	Delete an agent
`POST`	`/agents/{agent_id}/test`	Run a test message against the agent (sync JSON)
`POST`	`/agents/{agent_id}/chat`	Chat with an agent — streaming SSE or sync JSON

Workflows

Method	Endpoint	Description
`GET`	`/workflows`	List all workflows in project
`POST`	`/workflows`	Create a workflow
`GET`	`/workflows/{workflow_id}`	Get workflow (includes nodes + edges)
`PUT`	`/workflows/{workflow_id}`	Update workflow
`DELETE`	`/workflows/{workflow_id}`	Delete workflow
`POST`	`/workflows/{workflow_id}/execute`	Start a workflow execution
`PUT`	`/workflows/{workflow_id}/schedule`	Enable or disable the schedule trigger
`GET`	`/workflows/{workflow_id}/executions`	List executions for a specific workflow

Execute workflow response:

{
  "execution_id": "exec_abc123",
  "status": "pending"
}

Executions

Method	Endpoint	Description
`GET`	`/executions`	List executions (filterable by workflow_id, status)
`GET`	`/executions/{execution_id}`	Get execution details with node results
`GET`	`/executions/{execution_id}/stream`	SSE stream of live execution events
`GET`	`/executions/{execution_id}/logs`	Full execution logs (input/output per node)
`POST`	`/executions/{execution_id}/approve`	Approve or reject a Human-in-Loop node
`POST`	`/executions/{execution_id}/cancel`	Cancel a running execution

Get execution response:

{
  "id": "exec_abc123",
  "workflow_id": "wf_xyz",
  "status": "completed",
  "trigger": "schedule",
  "input": "",
  "output": "Analysis complete: 3 issues found.",
  "created_at": "2025-05-23T09:00:01Z",
  "completed_at": "2025-05-23T09:00:18Z",
  "node_results": {
    "node_1": {"status": "completed", "output": "Fetched 42 records.", "duration_ms": 1200},
    "node_2": {"status": "completed", "output": "Analysis complete: 3 issues found.", "duration_ms": 14800}
  }
}

Webhooks

Method	Endpoint	Description
`POST`	`/webhooks/setup/{workflow_id}`	Generate webhook URL and HMAC secret
`POST`	`/webhooks/{workflow_id}`	Receive a signed webhook (triggers execution)

RAG Sources

Method	Endpoint	Description
`GET`	`/rags`	List RAG sources in project
`POST`	`/rags`	Create a RAG source
`GET`	`/rags/{rag_id}`	Get RAG source details
`PUT`	`/rags/{rag_id}`	Update RAG source
`DELETE`	`/rags/{rag_id}`	Delete RAG source
`POST`	`/rags/{rag_id}/test`	Test RAG connection

MCP Servers

Method	Endpoint	Description
`GET`	`/mcp`	List connected MCP servers
`POST`	`/mcp`	Connect a new MCP server
`GET`	`/mcp/{mcp_id}`	Get MCP server details + tools
`DELETE`	`/mcp/{mcp_id}`	Disconnect MCP server
`POST`	`/mcp/discover`	Discover tools from an MCP endpoint

Skills

Skills are prompt + model bundles you can assign to agents. These are read-only from an integration perspective — create and manage them via the TARX UI.

Method	Endpoint	Description
`GET`	`/skills`	List available skills (builtin + project)
`GET`	`/skills/{skill_id}`	Get skill details

Credentials

Method	Endpoint	Description
`GET`	`/credentials`	List project credentials (names only)
`POST`	`/credentials`	Add a credential
`DELETE`	`/credentials/{cred_id}`	Delete a credential

Bridge is not an external API

Bridge (/api/v1/bridge) powers the TARX web UI's AI assistant and is not available via platform API keys. To chat with an agent programmatically, use POST /api/v1/agents/{agent_id}/chat — see the API Integration Guide.

Request/Response Patterns

List Responses

{
  "items": [...],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Create Responses

{
  "id": "new_resource_id",
  "created_at": "2024-01-15T10:30:00Z",
  ...all fields
}

Error Responses

{
  "detail": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE",
  "status": 400
}

Common error codes:

Code	HTTP Status	Description
`AUTH_REQUIRED`	401	Missing or invalid API key
`PERMISSION_DENIED`	403	Valid auth but insufficient role
`NOT_FOUND`	404	Resource doesn't exist or not in your project
`VALIDATION_ERROR`	422	Invalid request body
`RATE_LIMIT_EXCEEDED`	429	API rate limit hit

Rate Limiting

The API enforces rate limiting per IP:

Limit	Value
Requests per minute	200
Workflow executions per hour	100 (per project)
Burst	30 requests in 5 seconds

Rate limit headers are included in every response:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 147
X-RateLimit-Reset: 1705312200

When rate limited, the API returns 429 Too Many Requests. Back off and retry after X-RateLimit-Reset.

SSE Streaming

Execution events stream via Server-Sent Events:

GET /executions/{execution_id}/stream?token={api_key}

Note: SSE uses a query parameter for auth (not a header) because the browser's EventSource API doesn't support custom headers. Pass your Platform API Key as the token query parameter.

Event format:

event: node_start
data: {"node_id": "node_1", "node_type": "agentNode", "timestamp": "..."}

event: node_complete
data: {"node_id": "node_1", "output": "The result...", "duration_ms": 4200}

event: node_failed
data: {"node_id": "node_1", "error": "APIKeyNotFound", "duration_ms": 120}

event: execution_complete
data: {"execution_id": "exec_abc", "status": "completed", "duration_ms": 12400}

event: execution_failed
data: {"execution_id": "exec_abc", "status": "failed", "error": "..."}

Execute a Workflow (Example)

import requests, time

BASE_URL = "https://api.tarx.io/api/v1"
API_KEY = "sk-tarx-YOUR_KEY"
PROJECT_ID = "your_project_id"
WORKFLOW_ID = "your_workflow_id"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "X-Project-ID": PROJECT_ID,
    "Content-Type": "application/json",
}

# Execute workflow
response = requests.post(
    f"{BASE_URL}/workflows/{WORKFLOW_ID}/execute",
    headers=headers,
    json={"input": "artificial intelligence in healthcare"},
)

execution_id = response.json()["execution_id"]
print(f"Started: {execution_id}")

# Poll for completion
while True:
    status = requests.get(f"{BASE_URL}/executions/{execution_id}", headers=headers).json()
    if status["status"] in ["completed", "failed", "rejected"]:
        print(f"Done: {status['status']}")
        print(f"Output: {status['output']}")
        break
    time.sleep(2)

RBAC Enforcement

The API enforces role-based access control:

Operation	Required Role
`GET` (read any resource)	Any project member
`POST`, `PUT` (create/update resources)	Editor or Admin
`DELETE` (delete resources)	Editor or Admin
`POST /projects/{id}/members`	Admin only
`DELETE /projects/{id}/members`	Admin only
`POST /credentials`	Admin only
`DELETE /credentials`	Admin only

Attempting an operation without sufficient role returns 403 Forbidden.

Base URL​

Authentication​

Project Context​

Key Endpoints​

Authentication​

Users​

LLM Keys (BYOK)​

Platform API Keys​

Projects​

Agents​

Workflows​

Executions​

Webhooks​

RAG Sources​

MCP Servers​

Skills​

Credentials​

Request/Response Patterns​

List Responses​

Create Responses​

Error Responses​

Rate Limiting​

SSE Streaming​

Execute a Workflow (Example)​

RBAC Enforcement​

Base URL

Authentication

Project Context

Key Endpoints

Authentication

Users

LLM Keys (BYOK)

Platform API Keys

Projects

Agents

Workflows

Executions

Webhooks

RAG Sources

MCP Servers

Skills

Credentials

Request/Response Patterns

List Responses

Create Responses

Error Responses

Rate Limiting

SSE Streaming

Execute a Workflow (Example)

RBAC Enforcement