API Reference

Overview

The Condrox AI API exposes the cognitive pipeline over HTTP. It runs on FastAPI with Uvicorn. All request and response bodies use JSON.

Public Endpoints

POST /process

Process a natural language input through the full cognitive pipeline. This is the primary endpoint for conversational and code interactions.

• Auth: Required (X-API-Key)
• Rate limit: 30 req/min

Request body

{
  "text": "string",
  "context": "optional string",
  "mode": "optional string (code|analyze|architect|explain|default)"
}

Response 200

{
  "response": "string",
  "mode": "string",
  "intent": "string",
  "emotion": "string",
  "processing_time_ms": "number",
  "pipeline_stages": "array"
}

Other responses

• 429: Rate limited
• 401: Unauthorized

Example

curl -X POST http://localhost:8000/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Explain how the pipeline works", "mode": "explain"}'

GET /health

Health check endpoint. No authentication required.

• Auth: None

Response 200

{
  "status": "healthy",
  "version": "3.4.0",
  "uptime_seconds": "number"
}

Example

curl http://localhost:8000/health

GET /creative

Generate creative output through emotion to music mapping. Returns a music prompt and color palette derived from the input emotion.

• Auth: Required (X-API-Key)

Request body

{
  "emotion": "string",
  "text": "string"
}

Response 200

{
  "music_prompt": "string",
  "palette": "string",
  "emotion": "string"
}

Example

curl -X GET http://localhost:8000/creative \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emotion": "curious", "text": "stars over a quiet ocean"}'

GET /

API root. Returns a listing of available endpoints.

• Auth: None

Example

curl http://localhost:8000/

Admin Endpoints

24 endpoints for system administration. All require an admin-level API key sent in the X-API-Key header.

Health and Config

Memory Management

Knowledge Management

Agent Management

Pipeline Info

State Management

Authentication

All protected endpoints require the X-API-Key header. Admin endpoints require an admin-level key, which grants access to the /admin/* routes.

• Keys are stored in SQLite with bcrypt hashing
• Constant-time comparison prevents timing attacks
• Invalid keys return 401 Unauthorized
• Missing keys return 401 Unauthorized

curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/admin/memory

Rate Limiting

Limits are applied per IP address. The /process endpoint has a tighter cap because each request runs the full 18-stage pipeline.

• A 429 response includes a Retry-After header indicating when to retry
• Rate limits are configurable via environment variables

Error Handling

Every error response follows the same shape. The error_code field is a stable machine-readable identifier.

Error response shape

{
  "detail": "string",
  "error_code": "string"
}

SDK Examples

Python (requests)

import requests

BASE_URL = "http://localhost:8000"
API_KEY = "YOUR_API_KEY"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

# Process a request
response = requests.post(
    f"{BASE_URL}/process",
    headers=headers,
    json={"text": "Explain the reasoning engine", "mode": "explain"},
)
print(response.status_code)
print(response.json())

# Health check (no auth)
health = requests.get(f"{BASE_URL}/health")
print(health.json())

# Creative output
creative = requests.get(
    f"{BASE_URL}/creative",
    headers=headers,
    json={"emotion": "curious", "text": "a quiet forest at dawn"},
)
print(creative.json())

JavaScript (fetch)

const BASE_URL = "http://localhost:8000";
const API_KEY = "YOUR_API_KEY";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json",
};

// Process a request
fetch(`${BASE_URL}/process`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    text: "Refactor this function for readability",
    mode: "code",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

// Health check (no auth)
fetch(`${BASE_URL}/health`)
  .then((res) => res.json())
  .then((data) => console.log(data));

// Creative output
fetch(`${BASE_URL}/creative`, {
  method: "GET",
  headers,
  body: JSON.stringify({ emotion: "happy", text: "sunlight on water" }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

cURL

# Process
curl -X POST http://localhost:8000/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "What is BM25 retrieval", "mode": "explain"}'

# Health
curl http://localhost:8000/health

# Creative
curl -X GET http://localhost:8000/creative \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emotion": "philosophical", "text": "the shape of silence"}'

# Admin: list memory
curl -H "X-API-Key: YOUR_ADMIN_KEY" http://localhost:8000/admin/memory

# Admin: list pipeline stages
curl -H "X-API-Key: YOUR_ADMIN_KEY" http://localhost:8000/admin/pipeline/stages