# AIQaramba API Reference

Base URL: https://app.aiqaramba.com
Authentication: Bearer token via `Authorization: Bearer <api_key>` header

## Agents

Agents are autonomous browser-based workers that execute prompts against a target website. Each agent gets its own browser session, follows the instructions in its prompt, and reports back with results.

### POST /api/v1/agents

Create a new agent

Creates a new agent and enqueues it for execution. The agent will be assigned a browser session and begin following the prompt instructions.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| project_id | uuid | body | yes | - | ID of the project this agent belongs to |
| persona_id | uuid | body |  | - | Optional persona to use for this agent |
| name | string | body |  | - | Human-readable name for the agent |
| prompt | string | body | yes | - | Instructions for the agent to follow |
| model | string | body |  | gemini-3-flash-preview | LLM model to use |
| browser_type | string | body |  | chrome | Browser to use (chrome, firefox, edge) |
| max_tokens | integer | body |  | 2000000 | Maximum token budget for the agent's LLM calls |
| max_iterations | integer | body |  | 100 | Maximum number of LLM iterations before the agent stops |
| record_video | boolean | body |  | false | Whether to record a video of the browser session |
| clean_session | boolean | body |  | false | Clear all browser cookies before starting — prevents stale auth sessions from interfering |
| files | array | body |  | - | Initial files to place in the agent workspace (each with path and base64 content) |

### GET /api/v1/agents

List agents

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination (agent ID) |
| project | uuid | query |  | - | Filter by project ID |
| experiment | uuid | query |  | - | Filter by experiment ID (all runs) |
| experiment_run | uuid | query |  | - | Filter by specific experiment run ID |

### GET /api/v1/agents/{id}

Get agent by ID

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |

### DELETE /api/v1/agents/{id}

Delete an agent

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |

### POST /api/v1/agents/{id}/summarize

Generate agent summary

Uses an LLM to generate a summary of what the agent did. Only works on terminal agents (completed, failed, captcha).

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |
| force | boolean | query |  | false | Force regeneration of existing summary |

### GET /api/v1/agents/{id}/verification

Get agent verification result

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |

### POST /api/v1/agents/{id}/verify

Verify an agent

Runs verification checks on the agent's outcome.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |

### POST /api/v1/agents/{id}/retry

Retry an agent

Re-enqueues a terminal agent for another execution attempt.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |

### POST /api/v1/agents/{id}/files

Upload files to agent workspace

Upload files via multipart/form-data. Files are placed in the agent's workspace for use with browser_upload_file during execution. Max 50MB per request, 10MB per file.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Agent ID |
| path | string | body |  | - | Subdirectory to place files in (e.g. 'audio') |
| files | file[] | body | yes | - | One or more files (multipart form field name: 'files') |

## Projects

Projects are containers that organize agents, journeys, and experiments. Every agent must belong to a project.

### POST /api/v1/projects

Create a new project

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| name | string | body | yes | - | Project name |
| description | string | body |  | - | Project description |

### GET /api/v1/projects

List projects

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination |

### GET /api/v1/projects/{id}

Get project by ID

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Project ID |

### DELETE /api/v1/projects/{id}

Delete a project

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Project ID |

## Journeys

Journeys are reusable, parameterized agent templates. Define a prompt template using Go text/template syntax, add checkpoints for progress tracking, and set success criteria — then run the journey repeatedly with different inputs or personas.

### POST /api/v1/journeys

Create a new journey

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| project_id | uuid | body | yes | - | ID of the project this journey belongs to |
| name | string | body | yes | - | Journey name |
| description | string | body |  | - | Journey description |
| prompt_template | string | body | yes | - | Go text/template prompt with {{.Variables}} |
| entry_url | string | body | yes | - | Starting URL for the journey |
| checkpoints | json | body |  | - | Checkpoint definitions for progress tracking |
| success_criteria | json | body |  | - | Criteria to determine journey success |

### GET /api/v1/journeys

List journeys

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination |
| project | uuid | query |  | - | Filter by project ID |

### GET /api/v1/journeys/{id}

Get journey by ID

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Journey ID |

### PATCH /api/v1/journeys/{id}

Update a journey

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Journey ID |
| name | string | body |  | - | Journey name |
| description | string | body |  | - | Journey description |
| prompt_template | string | body |  | - | Go text/template prompt |
| entry_url | string | body |  | - | Starting URL |
| checkpoints | json | body |  | - | Checkpoint definitions |
| success_criteria | json | body |  | - | Success criteria |

### DELETE /api/v1/journeys/{id}

Delete a journey

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Journey ID |

### POST /api/v1/journeys/{id}/run

Run a journey

Creates a new agent from the journey template, rendering the prompt with the supplied variables.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Journey ID |
| persona_id | uuid | body |  | - | Persona for this run |
| variables | object | body |  | - | Template variables to inject into prompt_template |
| browser_type | string | body |  | chrome | Browser to use |
| record_video | boolean | body |  | false | Record a video of the session |
| files | array | body |  | - | Initial files for the agent workspace |

## Experiments

Experiments execute a matrix of journeys, personas, and browser types. The system computes the cartesian product and spawns one agent per combination, letting you compare results across all dimensions in a single run.

### POST /api/v1/experiments

Create a new experiment

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| project_id | uuid | body | yes | - | ID of the project |
| name | string | body | yes | - | Experiment name |
| description | string | body |  | - | Experiment description |
| mode | string | body |  | - | Experiment mode |
| matrix | json | body |  | - | Matrix configuration defining the test combinations |
| config | json | body |  | - | Additional experiment configuration |
| event_schema_id | uuid | body |  | - | Event schema for analytics tracking |

### GET /api/v1/experiments

List experiments

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination |
| project | uuid | query |  | - | Filter by project ID |

### GET /api/v1/experiments/{id}

Get experiment by ID

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |

### PATCH /api/v1/experiments/{id}

Update an experiment

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |
| name | string | body |  | - | Experiment name |
| description | string | body |  | - | Experiment description |
| mode | string | body |  | - | Experiment mode |
| matrix | json | body |  | - | Matrix configuration |
| config | json | body |  | - | Additional configuration |
| event_schema_id | uuid | body |  | - | Event schema ID |

### DELETE /api/v1/experiments/{id}

Delete an experiment

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |

### POST /api/v1/experiments/{id}/run

Run an experiment

Creates a new experiment run, spawning agents for each combination in the matrix.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |
| files | array | body |  | - | Initial files for agent workspaces |

### GET /api/v1/experiments/{id}/runs

List experiment runs

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination |

### GET /api/v1/experiments/{id}/runs/{run_id}

Get a specific experiment run

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |
| run_id | uuid | path | yes | - | Run ID |

### GET /api/v1/experiments/{id}/runs/{run_id}/agents

List agents in an experiment run

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |
| run_id | uuid | path | yes | - | Run ID |

### GET /api/v1/experiments/{id}/runs/{run_id}/comparison

Get comparison report for an experiment run

Returns a detailed comparison of agent results across personas, including aggregate statistics and optional analytics tracking health.

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Experiment ID |
| run_id | uuid | path | yes | - | Run ID |
| summarize | boolean | query |  | false | Auto-generate missing agent summaries |
| resummarize | boolean | query |  | false | Force regenerate all summaries |

## Personas

Personas define user archetypes that agents can embody. The persona description is injected verbatim into the agent's LLM system prompt, directly shaping how the agent interacts with the target site.

### POST /api/v1/personas

Create a new persona

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| name | string | body | yes | - | Persona name |
| description | string | body |  | - | Behavioral description for the persona |

### GET /api/v1/personas

List personas

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination |

### GET /api/v1/personas/{id}

Get persona by ID

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Persona ID |

### DELETE /api/v1/personas/{id}

Delete a persona

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Persona ID |

## Event Schemas

Event schemas define the analytics events that should be tracked during agent sessions. Attach a schema to an experiment to verify that the correct events fire during user journeys.

### POST /api/v1/event-schemas

Create a new event schema

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| project_id | uuid | body | yes | - | ID of the project |
| name | string | body | yes | - | Schema name |
| platform | string | body |  | - | Analytics platform identifier |
| credentials | json | body |  | - | Platform credentials for event verification |
| domains | json | body |  | - | Domains to monitor for events |
| events | json | body |  | - | Expected event definitions |

### GET /api/v1/event-schemas

List event schemas

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| limit | integer | query |  | 20 | Number of results to return |
| cursor | uuid | query |  | - | Cursor for pagination |
| project | uuid | query |  | - | Filter by project ID |

### GET /api/v1/event-schemas/{id}

Get event schema by ID

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Event schema ID |

### PATCH /api/v1/event-schemas/{id}

Update an event schema

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Event schema ID |
| name | string | body |  | - | Schema name |
| credentials | json | body |  | - | Platform credentials |
| domains | json | body |  | - | Domains to monitor |
| events | json | body |  | - | Expected event definitions |

### DELETE /api/v1/event-schemas/{id}

Delete an event schema

**Parameters:**

| Name | Type | Location | Required | Default | Description |
|------|------|----------|----------|---------|-------------|
| id | uuid | path | yes | - | Event schema ID |