Skip to main content

​
Welcome

The Subconscious API enables you to build powerful AI agents that can reason, use tools, and complete complex tasks. Our API is designed around Runs - discrete agent executions that process your instructions and return structured results.

​
Core Concepts

​
Runs

A Run represents a single agent execution. You provide instructions and optionally tools, and the agent works to complete the task. Runs can be:
  • Async (POST /v1/runs) - Queue a run and poll for results or receive webhooks
  • Streaming (POST /v1/runs/stream) - Stream execution events in real-time via SSE

​
Engines

Choose from multiple inference engines optimized for different use cases:
EngineTypeDescription
tim-edgeUnifiedHighly efficient engine tuned for performance with search tools
tim-gptCompoundComplex reasoning engine backed by OpenAI GPT-4.1
tim-gpt-heavyCompoundComplex reasoning engine backed by OpenAI GPT-5.2

​
Tools

Agents can use tools to interact with external systems:
  • Platform tools - Built-in capabilities like web search
  • Function tools - Your custom HTTP endpoints
  • MCP tools - Model Context Protocol servers

​
Structured Output

Request structured responses using JSON Schema via answerFormat and reasoningFormat fields.

​
Authentication

All API endpoints require Bearer token authentication: 
curl https://api.subconscious.dev/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine": "tim-gpt", "input": {"instructions": "..."}}'
Get your API key from the Subconscious platform.

​
Quick Example

​
Create an async run

curl -X POST https://api.subconscious.dev/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "tim-gpt",
    "input": {
      "instructions": "Research the latest developments in quantum computing"
    }
  }'
Response: 
{
  "runId": "run_abc123...",
  "status": "queued"
}

​
Poll for results

curl https://api.subconscious.dev/v1/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (when complete): 
{
  "runId": "run_abc123...",
  "status": "succeeded",
  "result": {
    "answer": "Recent developments in quantum computing include...",
    "reasoning": null
  },
  "usage": {
    "inputTokens": 1234,
    "outputTokens": 567,
    "durationMs": 45000
  }
}

​
Webhooks

Instead of polling, configure webhooks to receive notifications when runs complete: 
curl -X POST https://api.subconscious.dev/v1/webhooks/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://your-app.com/webhooks",
    "eventTypes": ["job.succeeded", "job.failed"]
  }'
Or attach a one-off callback URL to a specific run: 
{
  "engine": "tim-gpt",
  "input": { "instructions": "..." },
  "output": { "callbackUrl": "https://your-app.com/webhooks" }
}