Subconscious Platform

https://docs.subconscious.dev
Admin
Subconscious Platform is an AI agent infrastructure that provides generalized inference engines for...
Tokens:27,923
Snippets:172
Trust Score:5.9
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Subconscious SDK

Source: https://docs.subconscious.dev/quickstart

Install the Subconscious SDK for Node.js using npm or for Python using pip. These commands are necessary to integrate Subconscious into your projects.

```bash
npm install subconscious
```

```bash
pip install subconscious-sdk
```

--------------------------------

### Run First Agent with Subconscious SDK

Source: https://docs.subconscious.dev/quickstart

Execute your first agent using the Subconscious SDK. This example demonstrates how to initialize the client, define agent instructions, specify tools (like web search), and retrieve the summarized results. It supports Node.js (TypeScript) and Python.

```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

const run = await client.run({
  engine: "tim-large",
  input: {
    instructions:
      "Search for the latest AI news and summarize the top 3 stories",
    tools: [{ type: "platform", id: "web_search" }],
  },
  options: { awaitCompletion: true },
});

console.log(run.result?.answer);
```

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

run = client.run(
    engine="tim-large",
    input={
        "instructions": "Search for the latest AI news and summarize the top 3 stories",
        "tools": [{"type": "platform", "id": "web_search"}],
    },
    options={"await_completion": True},
)

print(run.result.answer)
```

--------------------------------

### Run First Agent with cURL

Source: https://docs.subconscious.dev/quickstart

Execute your first agent using a cURL command. This example demonstrates how to make a POST request to the Subconscious API to search for AI news and summarize the top stories, specifying the engine and tools.

```bash
curl https://api.subconscious.dev/v1/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "engine": "tim-large",
    "input": {
      "instructions": "Search for the latest AI news and summarize the top 3 stories",
      "tools": [{"type": "platform", "id": "web_search"}]
    }
  }'
```

--------------------------------

### Install and Use Subconscious SDKs (Node.js, Python)

Source: https://docs.subconscious.dev/libraries

Installs and demonstrates basic API requests using the official Subconscious SDKs for Node.js and Python. Requires an API key for authentication. The `client.run()` method is used to execute tasks on specified engines.

```bash
npm install subconscious
```

```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

const run = await client.run({
  engine: "tim-large",
  input: {
    instructions: "Your task here",
    tools: [],
  },
  options: { awaitCompletion: true },
});

console.log(run.result?.answer);
```

```bash
pip install subconscious-sdk
```

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

run = client.run(
    engine="tim-large",
    input={
        "instructions": "Your task here",
        "tools": [],
    },
    options={"await_completion": True},
)

print(run.result.answer);
```

--------------------------------

### Quick Start: Adding Tools to a Run

Source: https://docs.subconscious.dev/core-concepts/tools

Demonstrates how to include tools, such as web search, in an agent's run configuration using both Python and Node.js.

```APIDOC
## Quick Start: Adding Tools to a Run

### Description
This section shows how to add tools to any agent run. You can specify tools like `web_search` directly in the `input` object.

### Method
Client SDK method: `client.run()`

### Parameters
- `engine` (string) - The AI engine to use for the run.
- `input` (object) - The input for the agent, including instructions and tools.
  - `instructions` (string) - The task for the agent.
  - `tools` (array) - A list of tools available to the agent.
    - `type` (string) - The type of tool ('platform' or 'function').
    - `id` (string) - The ID of the platform tool (e.g., 'web_search').
- `options` (object) - Additional options for the run.
  - `await_completion` (boolean) - Whether to wait for the agent's completion.

### Request Example (Python)
```python
from subconscious import Subconscious
import os

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

run = client.run(
    engine="tim-large",
    input={
        "instructions": "Find the latest news about SpaceX",
        "tools": [
            {"type": "platform", "id": "web_search"}
        ]
    },
    options={"await_completion": True},
)
```

### Request Example (Node.js)
```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

const run = await client.run({
  engine: "tim-large",
  input: {
    instructions: "Find the latest news about SpaceX",
    tools: [{ type: "platform", id: "web_search" }],
  },
  options: { awaitCompletion: true },
});
```
```

--------------------------------

### Webhook Handler Implementation Examples

Source: https://docs.subconscious.dev/core-concepts/async-webhooks

Provides example code for building a webhook handler endpoint in Python (FastAPI) and Node.js (Express) to process incoming webhook POST requests.

```APIDOC
## Webhook Handler Examples

### Description
Examples of how to implement a webhook handler endpoint to receive and process the POST requests sent by the Subconscious Webhooks API.

### Python (FastAPI)
```python
from fastapi import FastAPI, Request
import json

app = FastAPI()

@app.post("/webhooks/subconscious")
async def handle_webhook(request: Request):
    payload = await request.json()

    run_id = payload.get("runId")
    status = payload.get("status")

    if status == "succeeded":
        # Extract the answer from the result
        content = payload["result"]["choices"][0]["message"]["content"]
        parsed = json.loads(content)
        answer = parsed.get("answer", "")
        print(f"Run {run_id} completed: {answer[:100]}...")
        # Save to database, trigger next step, etc.
    elif status == "failed":
        print(f"Run {run_id} failed: {payload.get('error')}")

    return {"received": True}

# Run with: uvicorn server:app --host 0.0.0.0 --port 8000
```

### Node.js (Express)
```javascript
import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/subconscious", (req, res) => {
  const { runId, status, result, error } = req.body;

  if (status === "succeeded") {
    // Extract the answer from the result
    const content = result.choices[0].message.content;
    const parsed = JSON.parse(content);
    console.log(`Run ${runId} completed:`, parsed.answer?.slice(0, 100));
    // Save to database, trigger next step, etc.
  } else if (status === "failed") {
    console.error(`Run ${runId} failed:`, error);
  }

  // Always respond quickly with 2xx
  res.status(200).json({ received: true });
});

app.listen(8000, () => console.log("Webhook server running on :8000"));
```

### Note
Your webhook endpoint must be publicly accessible. For local development, consider using tools like [ngrok](https://ngrok.com).
```

--------------------------------

### Run First Agent with Python

Source: https://docs.subconscious.dev/index

This Python snippet demonstrates how to initialize the Subconscious client and run a generalized inference engine (tim-large) with specific instructions. It shows how to set API keys, define input, and retrieve the final answer.

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

run = client.run(
engine="tim-large",
input={"instructions": "Summarize the latest AI news"},
options={"await_completion": True},
)

print(run.result.answer)

```

--------------------------------

### GET /runs

Source: https://docs.subconscious.dev/api-reference/list-runs

Lists all runs for the authenticated organization. Supports pagination and filtering.

```APIDOC
## GET /runs

### Description
List all runs for the authenticated organization.

### Method
GET

### Endpoint
/runs

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of runs to return (default: 50, max: 100)
- **cursor** (string) - Optional - Pagination cursor from previous response

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **runs** (array) - List of runs. Each run contains `runId`, `status`, `engine`, `createdAt`, and `updatedAt`.
- **nextCursor** (string) - Pagination cursor for next page (null if no more pages)

#### Response Example
```json
{
  "runs": [
    {
      "runId": "run_abc123",
      "status": "succeeded",
      "engine": "tim-large",
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:05:00Z"
    }
  ],
  "nextCursor": "cursor_xyz789"
}
```

#### Error Response (401)
- **error** (object) - Contains error details including message, type, param, code, details, requestId, and runId.

#### Error Response (500)
- **error** (object) - Contains error details including message, type, param, code, details, requestId, and runId.
```

--------------------------------

### Run an AI Engine (Python, Node.js)

Source: https://docs.subconscious.dev/overview

Demonstrates how to run an AI engine using the Subconscious client library. This example shows how to initialize the client, specify the engine, provide input instructions, and retrieve the result. It requires an API key for authentication.

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

run = client.run(
engine="tim-large",
input={"instructions": "Summarize the latest AI news"},
options={"await_completion": True},
)

print(run.result.answer)

```

```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

const run = await client.run({
  engine: "tim-large",
  input: { instructions: "Summarize the latest AI news" },
  options: { awaitCompletion: true },
});

console.log(run.result?.answer);

```

--------------------------------

### SDK Exception Handling

Source: https://docs.subconscious.dev/guides/error-handling

Examples of how to catch and handle specific exceptions thrown by the SDKs for Python and Node.js.

```APIDOC
## SDK Exceptions

Both SDKs throw typed exceptions you can catch:

### Python

```python
from subconscious import Subconscious
from subconscious.errors import (
    SubconsciousError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
)
import os

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

try:
    run = client.run(
        engine="tim-large",
        input={"instructions": "Hello"},
        options={"await_completion": True},
    )
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except SubconsciousError as e:
    print(f"Error {e.status}: {e.code} - {e.message}")
```

### Node.js

```typescript
import {
  Subconscious,
  SubconsciousError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
} from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

try {
  const run = await client.run({
    engine: "tim-large",
    input: { instructions: "Hello" },
    options: { awaitCompletion: true },
  });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (e instanceof ValidationError) {
    console.error(`Bad request: ${e.message}`);
  } else if (e instanceof SubconsciousError) {
    console.error(`Error ${e.status}: ${e.code} - ${e.message}`);
  }
}
```

Exception properties:

* `code` — Error type (`"invalid_request"`, `"authentication_failed"`, etc.)
* `status` — HTTP status code
* `message` — Human-readable message
* `details` — Additional context (validation errors)
```

--------------------------------

### Create Async Run - Bash

Source: https://docs.subconscious.dev/api-reference/introduction

Provides a bash example for initiating an asynchronous AI agent run. It specifies the 'tim-large' engine and provides instructions for the agent to execute. The response includes a run ID and initial status.

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

--------------------------------

### Platform Tools

Source: https://docs.subconscious.dev/core-concepts/tools

Lists and describes the built-in tools provided by Subconscious that require no additional setup.

```APIDOC
## Platform Tools

### Description
Platform tools are built-in functionalities hosted by Subconscious. They are readily available for use in agent runs without any setup required on your end.

### Available Tools

| ID                      | Name             | Description                                           |
| ----------------------- | ---------------- | ----------------------------------------------------- |
| `web_search`            | Google Search    | Search the web for information                        |
| `webpage_understanding` | Jina Reader      | Extract and summarize webpage content                 |
| `parallel_search`       | Parallel Search  | Precision search for facts from authoritative sources |
| `parallel_extract`      | Parallel Extract | Extract specific content from a webpage               |
| `exa_search`            | Exa Search       | Semantic search for high-quality content              |
| `exa_crawl`             | Exa Crawl        | Retrieve full webpage content                         |
| `exa_find_similar`      | Exa Similar      | Find pages similar to a given URL                     |
```

--------------------------------

### Build a Tool Server with FastAPI (Python)

Source: https://docs.subconscious.dev/core-concepts/tools

Provides a Python example using FastAPI to build a simple web server that acts as a custom tool. This server exposes a '/weather' endpoint that accepts POST requests with city and unit parameters and returns weather information.

```python
# server.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class WeatherRequest(BaseModel):
    city: str
    units: str = "celsius"

@app.post("/weather")
async def get_weather(req: WeatherRequest):
    # Your logic here - call weather API, database, etc.
    return {
        "city": req.city,
        "temperature": 22,
        "units": req.units,
        "condition": "sunny"
    }

# Run with: uvicorn server:app --host 0.0.0.0 --port 8000
```

--------------------------------

### Using answerFormat with JSON Schema

Source: https://docs.subconscious.dev/core-concepts/structured-output

This example demonstrates how to use the `answerFormat` field with a JSON Schema to define the structure of the agent's response. The response is automatically parsed into a dictionary or object.

```APIDOC
## POST /run

### Description
Submits a request to the Subconscious API to run an engine with specified instructions and an optional structured output format.

### Method
POST

### Endpoint
/run

### Parameters
#### Query Parameters
None

#### Request Body
- **engine** (string) - Required - The name of the engine to use (e.g., "tim-large").
- **input** (object) - Required - The input payload for the engine.
  - **instructions** (string) - Required - The instructions for the agent.
  - **tools** (array) - Optional - A list of tools the agent can use.
  - **answerFormat** (object | class) - Optional - A JSON Schema object or Pydantic model defining the desired output structure.
- **options** (object) - Optional - Additional options for the request.
  - **await_completion** (boolean) - Optional - Whether to wait for the completion of the task.

### Request Example
```json
{
  "engine": "tim-large",
  "input": {
    "instructions": "Analyze the sentiment of this review: 'Great product, fast shipping!'",
    "tools": [],
    "answerFormat": {
      "type": "object",
      "title": "SentimentAnalysis",
      "properties": {
        "sentiment": {
          "type": "string",
          "enum": ["positive", "negative", "neutral"],
          "description": "The overall sentiment"
        },
        "confidence": {
          "type": "number",
          "description": "Confidence score from 0 to 1"
        },
        "keywords": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Key phrases that influenced the sentiment"
        }
      },
      "required": ["sentiment", "confidence", "keywords"]
    }
  },
  "options": {"await_completion": true}
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the engine run.
  - **answer** (object) - The parsed answer matching the `answerFormat` schema.

#### Response Example
```json
{
  "result": {
    "answer": {
      "sentiment": "positive",
      "confidence": 0.95,
      "keywords": ["Great product", "fast shipping"]
    }
  }
}
```
```

--------------------------------

### Configure MCP Tools in an Agent (JavaScript)

Source: https://docs.subconscious.dev/core-concepts/tools

Provides examples of how to configure MCP tools within an agent's configuration using JavaScript. It demonstrates connecting to all tools on a server or a specific tool with authentication.

```javascript
tools: [
  // Use all tools from an MCP server
  { type: "mcp", server: "https://mcp.example.com" },

  // Use a specific tool with auth
  {
    type: "mcp",
    server: "https://mcp.example.com",
    name: "query_database",
    auth: { type: "bearer", token: "your-token" },
  },
];
```

--------------------------------

### Build a Tool Server with Express (Node.js)

Source: https://docs.subconscious.dev/core-concepts/tools

Provides a Node.js example using Express to build a simple web server that acts as a custom tool. This server exposes a '/weather' endpoint that accepts POST requests with city and unit parameters and returns weather information.

```typescript
// server.ts
import express from "express";

const app = express();
app.use(express.json());

app.post("/weather", (req, res) => {
  const { city, units = "celsius" } = req.body;

  // Your logic here - call weather API, database, etc.
  res.json({
    city,
    temperature: 22,
    units,
    condition: "sunny",
  });
});

app.listen(8000, () => console.log("Tool server running on :8000"));
```

--------------------------------

### Get a Run

Source: https://docs.subconscious.dev/api-reference/get-a-run

Retrieve the status and results of a specific run.

```APIDOC
## GET /websites/subconscious_dev/runs/{run_id}

### Description
Retrieve the status and results of a specific run.

### Method
GET

### Endpoint
/websites/subconscious_dev/runs/{run_id}

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.

### Response
#### Success Response (200)
- **status** (string) - The current status of the run (e.g., "pending", "running", "completed", "failed").
- **results** (object) - An object containing the results of the run. The structure of this object may vary depending on the type of run.

#### Response Example
```json
{
  "status": "completed",
  "results": {
    "accuracy": 0.95,
    "precision": 0.92
  }
}
```
```

--------------------------------

### Start Asynchronous Run and Check Status (Node.js)

Source: https://docs.subconscious.dev/core-concepts/runs

Starts an agent run asynchronously in Node.js, returning the run ID for later status checks. This approach is beneficial for tasks that do not require immediate results and can be processed in the background.

```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

// Start without waiting
const run = await client.run({
  engine: "tim-large",
  input: { instructions: "Generate a report" },
});

console.log(`Run started: ${run.runId}`);

// Check status later
const status = await client.get(run.runId);
console.log(status.status);
```

--------------------------------

### Combining Tools

Source: https://docs.subconscious.dev/core-concepts/tools

Agents can utilize multiple tools simultaneously. This section provides an example of combining platform tools for web research with a custom API function for saving data.

```APIDOC
## Combining Tools

Agents can use multiple tools together.

### Example

```javascript
tools: [
  // Platform tools for web research
  { type: "platform", id: "web_search" },
  { type: "platform", id: "webpage_understanding" },

  // Your custom API
  {
    type: "function",
    name: "save_to_database",
    description: "Save research findings to our database",
    url: "https://api.example.com/save",
    method: "POST",
    parameters: {
      type: "object",
      properties: {
        title: { type: "string" },
        content: { type: "string" },
        tags: { type: "array", items: { type: "string" } },
      },
      required: ["title", "content"],
    },
  },
]
```
```

--------------------------------

### Cancel a Run (Python and Node.js)

Source: https://docs.subconscious.dev/core-concepts/runs

Demonstrates how to cancel a run that is currently in progress using the Subconscious client library. Examples are provided for both Python and Node.js environments.

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

# Cancel a run in progress
client.cancel(run.run_id)
```

```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

// Cancel a run in progress
await client.cancel(run.runId);
```

--------------------------------

### Python: Structured Reasoning Output with reasoningFormat

Source: https://docs.subconscious.dev/core-concepts/structured-output

This Python snippet shows how to configure the `reasoningFormat` when running an engine. It specifies a JSON schema for the expected output, including an object with a 'steps' array, where each step has an 'action' and 'result'. This is useful for guiding the agent to produce predictable, structured responses, particularly when using tools like web search.

```python
run = client.run(
    engine="tim-large",
    input={
        "instructions": "Research and compare two products",
        "tools": [{"type": "platform", "id": "web_search"}],
        "answerFormat": {},
        "reasoningFormat": {
            "type": "object",
            "title": "ResearchSteps",
            "properties": {
                "steps": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "action": {"type": "string"},
                            "result": {"type": "string"}
                        }
                    }
                }
            },
            "required": ["steps"]
        }
    },
    options={"await_completion": True},
)

```

--------------------------------

### Use Pydantic Models for Structured Output in Python

Source: https://docs.subconscious.dev/core-concepts/structured-output

This Python example demonstrates using Pydantic models with the Subconscious SDK to automatically generate JSON Schemas for structured output. By passing a Pydantic model class directly to `answerFormat`, the SDK handles the schema conversion, ensuring type-safe responses that can be accessed directly.

```python
from subconscious import Subconscious
from pydantic import BaseModel
import os

class SentimentAnalysis(BaseModel):
    sentiment: str
    confidence: float
    keywords: list[str]

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

run = client.run(
    engine="tim-large",
    input={
        "instructions": "Analyze the sentiment of: 'Great product!'",
        "answerFormat": SentimentAnalysis,  # Pass the class directly
    },
    options={"await_completion": True},
)

print(run.result.answer["sentiment"])
```

--------------------------------

### Start Asynchronous Run and Check Status (Python)

Source: https://docs.subconscious.dev/core-concepts/runs

Initiates an agent run without waiting for completion, allowing for background execution. The run ID is returned, and its status can be checked later using `client.get()`. This is ideal for long-running tasks.

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

# Start without waiting
run = client.run(
    engine="tim-large",
    input={"instructions": "Generate a report"},
)

print(f"Run started: {run.run_id}")

# Check status later
status = client.get(run.run_id)
print(status.status)  # 'queued' | 'running' | 'succeeded' | 'failed'
```

--------------------------------

### POST /runs/stream

Source: https://docs.subconscious.dev/api-reference/create-and-stream-a-run

Creates a run and streams execution events via Server-Sent Events (SSE). Uses OpenAI-compatible SSE format.

```APIDOC
## POST /runs/stream

### Description
Creates a run and streams execution events via Server-Sent Events (SSE). Uses OpenAI-compatible SSE format.

### Method
POST

### Endpoint
/runs/stream

### Parameters
#### Request Body
- **engine** (string) - Required - The engine to use for this run. Enum: `tim-small-preview`, `tim-large`, `tim-test`
- **input** (object) - Required - The input for the run. See `RunInput` schema.
- **output** (object) - Optional - See `RunOutput` schema.
- **options** (object) - Optional - See `RunOptions` schema.

### Request Example
```json
{
  "engine": "tim-small-preview",
  "input": {
    "instructions": "Write a short story about a robot learning to love."
  }
}
```

### Response
#### Success Response (200)
- **text/event-stream** (string) - Server-Sent Events stream of run events

#### Response Example
```
event: content
data: {"type": "text", "value": "Once upon a time..."}

event: done
data: {"runId": "run_abc123"}
```

#### Error Responses
- **400** - Bad request. See `Error` schema.
- **401** - Unauthorized. See `Error` schema.
- **500** - Internal server error. See `Error` schema.
```

--------------------------------

### GET /runs/{runId}

Source: https://docs.subconscious.dev/api-reference/get-a-run

Retrieve the status and results of a specific AI agent run using its unique identifier.

```APIDOC
## GET /runs/{runId}

### Description
Retrieve the status and results of a specific run.

### Method
GET

### Endpoint
/runs/{runId}

### Parameters
#### Path Parameters
- **runId** (string) - Required - The ID of the run to retrieve

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **runId** (string) - Unique identifier for the run
- **status** (string) - Current status of the run (queued, running, succeeded, failed, canceled, timed_out)
- **result** (object) - Run result (only present for terminal states)
- **usage** (object) - Token usage and timing (only present for terminal states)
- **error** (object) - Error details (only present for failed runs)

#### Response Example
```json
{
  "runId": "run-12345",
  "status": "succeeded",
  "result": {
    "answer": "The answer to the query.",
    "reasoning": {
      "step1": "Initial thought process."
    }
  },
  "usage": {
    "inputTokens": 100,
    "outputTokens": 50,
    "toolCalls": {
      "calculator": 1
    },
    "durationMs": 2500
  }
}
```

#### Error Response (400, 401, 403, 404, 500)
- **error** (string or object) - Error details
- **details** (object) - Additional error details (for validation errors)
- **requestId** (string) - Request ID for debugging
- **runId** (string) - Run ID (if applicable)

#### Error Response Example
```json
{
  "error": {
    "message": "Run not found.",
    "type": "not_found",
    "code": "run_not_found"
  },
  "requestId": "req-abcde"
}
```
```

--------------------------------

### POST /runs

Source: https://docs.subconscious.dev/api-reference/create-a-new-agent-run

Creates a new agent run. The run is processed asynchronously. Use the returned runId to poll for status or set up webhooks to receive notifications.

```APIDOC
## POST /runs

### Description
Creates a new agent run. The run is processed asynchronously. Use the returned runId to poll for status or set up webhooks to receive notifications.

### Method
POST

### Endpoint
/runs

### Parameters
#### Request Body
- **engine** (string) - Required - The engine to use for this run. Enum: `tim-small-preview`, `tim-large`, `tim-test`
- **input** (object) - Required - The input for the run, including instructions and optional tools.
  - **instructions** (string) - Required - The instructions for the agent to execute.
  - **tools** (array) - Optional - Array of tools the agent can use.
  - **answerFormat** (object) - Optional - JSON schema for the answer format.
  - **reasoningFormat** (object) - Optional - JSON schema for the reasoning format.
- **output** (object) - Optional - Output configuration for the run.
  - **callbackUrl** (string) - Optional - Callback URL to receive webhook notifications.
- **options** (object) - Optional - Options for the run.
  - **timeout** (integer) - Optional - Timeout in seconds (max 1 hour).

### Request Example
```json
{
  "engine": "tim-small-preview",
  "input": {
    "instructions": "Summarize the following text.",
    "text": "This is a long text that needs to be summarized."
  },
  "output": {
    "callbackUrl": "https://example.com/webhook"
  },
  "options": {
    "timeout": 60
  }
}
```

### Response
#### Success Response (201)
- **runId** (string) - Unique identifier for the run.
- **status** (string) - Initial status of the run (e.g., `queued`).

#### Response Example
```json
{
  "runId": "run-12345",
  "status": "queued"
}
```

#### Error Responses
- **400 Bad Request**: Invalid input provided.
- **401 Unauthorized**: Authentication failed.
- **409 Idempotency Conflict**: A run with the same idempotency key already exists.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

--------------------------------

### GET /v1/runs/{runId}

Source: https://docs.subconscious.dev/api-reference/introduction

Retrieves the status and results of a specific asynchronous run by its ID. Use this endpoint for polling.

```APIDOC
## GET /v1/runs/{runId}

### Description
Retrieves the status and results of a specific asynchronous run by its ID. Use this endpoint for polling.

### Method
GET

### Endpoint
/v1/runs/{runId}

### Parameters
#### Path Parameters
- **runId** (string) - Required - The unique identifier of the run to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://api.subconscious.dev/v1/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **runId** (string) - The unique identifier for the run.
- **status** (string) - The current status of the run (e.g., `succeeded`, `failed`, `processing`).
- **result** (object) - The result of the run if completed.
  - **answer** (string) - The final answer generated by the agent.
  - **reasoning** (string) - The reasoning process of the agent (can be null).
- **usage** (object) - Information about token usage and duration.
  - **inputTokens** (integer) - The number of input tokens used.
  - **outputTokens** (integer) - The number of output tokens generated.
  - **durationMs** (integer) - The total execution time in milliseconds.

#### Response Example
```json
{
  "runId": "run_abc123...",
  "status": "succeeded",
  "result": {
    "answer": "Recent developments in quantum computing include...",
    "reasoning": null
  },
  "usage": {
    "inputTokens": 1234,
    "outputTokens": 567,
    "durationMs": 45000
  }
}
```
```

--------------------------------

### Fetch Navigation and Pages

Source: https://docs.subconscious.dev/api-reference/create-and-stream-a-run

Retrieve navigation links and page content from the Subconscious documentation.

```APIDOC
## GET /llms.txt

### Description
Fetches the `llms.txt` file, which contains navigation and other page information for the Subconscious documentation.

### Method
GET

### Endpoint
/llms.txt

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **content** (string) - The content of the `llms.txt` file.

#### Response Example
```
{
  "content": "# Navigation\n- Home: /\n- About: /about\n\n# Pages\n## Home\nWelcome to the Subconscious platform!\n## About\nLearn more about us."
}
```
```

--------------------------------

### Function Tool Schema Definition

Source: https://docs.subconscious.dev/api-reference/create-and-stream-a-run

Defines the schema for a function tool, used for invoking specific functions via HTTP. It requires 'type', 'name', 'description', 'url', 'method' (POST or GET), and 'parameters'. An optional 'timeout' can be specified.

```json
{
  "type": "object",
  "required": [
    "type",
    "name",
    "description",
    "url",
    "method",
    "parameters"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "function"
      ],
      "description": "Tool type"
    },
    "name": {
      "type": "string",
      "description": "Function name"
    },
    "description": {
      "type": "string",
      "description": "Function description"
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "HTTP endpoint URL"
    },
    "method": {
      "type": "string",
      "enum": [
        "POST",
        "GET"
      ],
      "description": "HTTP method"
    },
    "timeout": {
      "type": "integer",
      "description": "Timeout in seconds (default: 30)"
    },
    "parameters": {
      "$ref": "#/components/schemas/ToolParameters"
    }
  }
}
```

--------------------------------

### Track Run Costs Using Usage Information (Python)

Source: https://docs.subconscious.dev/guides/response-handling

Demonstrates how to calculate the cost of a run using the `RunUsage` data in Python. It accesses input and output tokens from the `usage` object and applies tim-large pricing to compute the total cost. This snippet is useful for cost monitoring.

```python
usage = run.usage
input_cost = usage.input_tokens / 1_000_000 * 2.00  # tim-large pricing
output_cost = usage.output_tokens / 1_000_000 * 8.00
total_cost = input_cost + output_cost
print(f"Run cost: ${total_cost:.4f}")
```

--------------------------------

### Handle Stream Errors in Node.js and Python

Source: https://docs.subconscious.dev/core-concepts/streaming

Provides examples for gracefully handling errors that may occur during a streaming API request. It demonstrates how to catch both connection errors and specific stream errors, ensuring a more robust application.

```typescript
try {
  for await (const event of stream) {
    if (event.type === "delta") {
      process.stdout.write(event.content);
    } else if (event.type === "error") {
      console.error("Stream error:", event.error);
      break;
    }
  }
} catch (error) {
  console.error("Connection error:", error);
}
```

```python
try:
    for event in client.stream(...):
        if event.type == "delta":
            print(event.content, end="", flush=True)
        elif event.type == "error":
            print(f"Stream error: {event.error}")
            break
except Exception as e:
    print(f"Connection error: {e}")
```

--------------------------------

### Poll for Run Completion with `client.wait()` (Python)

Source: https://docs.subconscious.dev/core-concepts/runs

Starts an agent run and then automatically polls for its completion using `client.wait()`. This method allows specifying polling intervals and maximum attempts, providing a convenient way to wait for results.

```python
from subconscious import Subconscious

client = Subconscious(api_key="your-api-key")

# Start a run
run = client.run(
    engine="tim-large",
    input={"instructions": "Generate a detailed report"},
)

# Poll until complete
result = client.wait(
    run.run_id,
    options={
        "interval_ms": 2000,  # Poll every 2 seconds
        "max_attempts": 60,   # Give up after 60 attempts
    },
)

print(result.result.answer)
```

--------------------------------

### Authenticate and Create Async Run - Bash

Source: https://docs.subconscious.dev/api-reference/introduction

Demonstrates how to authenticate with the Subconscious API using a Bearer token and create an asynchronous run. This involves sending a POST request to the /v1/runs endpoint with the desired engine and instructions.

```bash
curl https://api.subconscious.dev/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine": "tim-large", "input": {"instructions": "..."}}'
```

--------------------------------

### Using Pydantic Models (Python SDK)

Source: https://docs.subconscious.dev/core-concepts/structured-output

Demonstrates how the Python SDK automatically converts Pydantic models into JSON Schemas for structured output.

```APIDOC
## POST /run (with Pydantic Models)

### Description
Submits a request to the Subconscious API using a Pydantic model to define the structured output. The Python SDK handles the conversion of the Pydantic model to a JSON Schema.

### Method
POST

### Endpoint
/run

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **engine** (string) - Required - The name of the engine to use (e.g., "tim-large").
- **input** (object) - Required - The input payload for the engine.
  - **instructions** (string) - Required - The instructions for the agent.
  - **answerFormat** (class) - Required - A Pydantic model class defining the desired output structure.
- **options** (object) - Optional - Additional options for the request.
  - **await_completion** (boolean) - Optional - Whether to wait for the completion of the task.

### Request Example
```python
from subconscious import Subconscious
from pydantic import BaseModel
import os

class SentimentAnalysis(BaseModel):
    sentiment: str
    confidence: float
    keywords: list[str]

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

run = client.run(
    engine="tim-large",
    input={
        "instructions": "Analyze the sentiment of: 'Great product!'",
        "answerFormat": SentimentAnalysis,  # Pass the class directly
    },
    options={"await_completion": True},
)

print(run.result.answer["sentiment"])
```

### Response
#### Success Response (200)
- **result** (object) - The result of the engine run.
  - **answer** (dict) - The parsed answer matching the Pydantic model schema.

#### Response Example
```json
{
  "result": {
    "answer": {
      "sentiment": "positive",
      "confidence": 0.95,
      "keywords": ["Great product"]
    }
  }
}
```
```

--------------------------------

### Add Tools to a Subconscious Run (Python, Node.js)

Source: https://docs.subconscious.dev/core-concepts/tools

Demonstrates how to add tools, specifically the 'web_search' platform tool, to a Subconscious agent run. This allows the agent to perform actions like searching the web. It shows the implementation in both Python and Node.js.

```python
from subconscious import Subconscious
import os

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

run = client.run(
    engine="tim-large",
    input={
        "instructions": "Find the latest news about SpaceX",
        "tools": [
            {"type": "platform", "id": "web_search"}
        ]
    },
    options={"await_completion": True},
)
```

```typescript
import { Subconscious } from "subconscious";

const client = new Subconscious({
  apiKey: process.env.SUBCONSCIOUS_API_KEY!,
});

const run = await client.run({
  engine: "tim-large",
  input: {
    instructions: "Find the latest news about SpaceX",
    tools: [{ type: "platform", id: "web_search" }],
  },
  options: { awaitCompletion: true },
});
```

--------------------------------

### Create Agent Run

Source: https://docs.subconscious.dev/api-reference/create-a-new-agent-run

Creates a new agent run. The run is processed asynchronously. Use the returned runId to poll for status or set up webhooks to receive notifications.

```APIDOC
## POST /websites/subconscious_dev/agent_runs

### Description
Creates a new agent run. The run is processed asynchronously. Use the returned runId to poll for status or set up webhooks to receive notifications.

### Method
POST

### Endpoint
/websites/subconscious_dev/agent_runs

### Parameters
#### Query Parameters
- **run_name** (string) - Optional - The name of the run.
- **model** (string) - Optional - The model to use for the run.
- **tools** (array) - Optional - A list of tools to use for the run.
- **description** (string) - Optional - A description of the run.
- **metadata** (object) - Optional - Metadata for the run.

### Request Body
```json
{
  "prompt": "string",
  "variables": {
    "additionalProperties": "string"
  }
}
```

### Response
#### Success Response (200)
- **runId** (string) - The ID of the created run.
- **status** (string) - The initial status of the run (e.g., "pending", "processing").

#### Response Example
```json
{
  "runId": "run_abc123",
  "status": "pending"
}
```
```

--------------------------------

### Poll for Run Results - Bash

Source: https://docs.subconscious.dev/api-reference/introduction

Illustrates how to poll the Subconscious API for the results of a previously initiated asynchronous run. This involves sending a GET request to the /v1/runs/{runId} endpoint. The response indicates the run's status and, upon completion, provides the agent's answer and reasoning.

```bash
curl https://api.subconscious.dev/v1/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Subscribe to Webhook Events - Bash

Source: https://docs.subconscious.dev/api-reference/introduction

Shows how to set up webhook subscriptions to receive real-time notifications for AI run events, such as job success or failure. This POST request to /v1/webhooks/subscriptions configures a callback URL.

```bash
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"]
  }'
```

--------------------------------

### Create a Run with Callback URL (Bash)

Source: https://docs.subconscious.dev/core-concepts/async-webhooks

This snippet demonstrates how to create a new run using the Subconscious Dev API and specify a callback URL to receive results. It requires the `SUBCONSCIOUS_API_KEY` environment variable and sends a JSON payload with the engine, input instructions, and the callback URL.

```bash
curl -X POST https://api.subconscious.dev/v1/runs \
  -H "Authorization: Bearer $SUBCONSCIOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "tim-large",
    "input": {
      "instructions": "Generate a detailed report"
    },
    "output": {
      "callbackUrl": "https://your-server.com/webhooks/subconscious"
    }
  }'
```

--------------------------------

### LLM Navigation and Content Retrieval

Source: https://docs.subconscious.dev/api-reference/get-a-run

This endpoint allows you to fetch navigation and other page content, specifically the llms.txt file, from the Subconscious platform.

```APIDOC
## GET /llms.txt

### Description
Fetches the llms.txt file, which contains navigation and other page information for the Subconscious documentation.

### Method
GET

### Endpoint
/llms.txt

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **content** (string) - The content of the llms.txt file, typically containing navigation links and descriptions.

#### Response Example
```json
{
  "content": "- **LLM Documentation**: Access detailed information about Large Language Models available on the platform.\n  - **API Endpoints**: Explore available API endpoints for programmatic access.\n  - **Platform Features**: Discover various features offered by the Subconscious platform."
}
```
```

--------------------------------

### Check Run Status and Handle Errors in Node.js

Source: https://docs.subconscious.dev/guides/error-handling

This Node.js snippet shows how to check the status of a run and handle various outcomes like succeeded, failed, timed_out, or canceled. It utilizes the client library to start a run and a switch statement to process the run's status, accessing either the result or error details.

```typescript
const run = await client.run({
  engine: "tim-large",
  input: { instructions: "Your task" },
  options: { awaitCompletion: true },
});

switch (run.status) {
  case "succeeded":
    console.log(run.result?.answer);
    break;
  case "failed":
    console.error("Failed:", run.error);
    break;
  case "timed_out":
    console.error("Timed out");
    break;
  case "canceled":
    console.log("Canceled");
    break;
}
```
Tokens:
Raw