API Reference

The Aiqaramba API gives you full programmatic access to everything the platform can do. Create projects, define tests, launch agents, check results, manage schedules. All endpoints live under /api/v1/, accept JSON, and require Bearer token authentication.

Most people use the API to set up their test tests and schedules, but you can also build custom solutions around it. Want a custom CI/CD pipeline that triggers test runs after every deploy and blocks the release if something fails? Want a dashboard that aggregates test results across multiple projects? The API gives you everything you need to build that.

LLM-ready reference

The entire API reference is available as a single plain-text markdown file at /docs/llm.txt. This follows the emerging llms.txt standard for exposing API documentation to LLMs and coding agents. Paste it into your coding agent, ChatGPT, Claude, or any LLM and it can write API calls for you.

Base URL

Authentication

All API requests require a Bearer token in the Authorization header. You can create and manage API keys from your account settings.

Authorization: Bearer YOUR_API_KEY

Rate Limits

The API enforces rate limits per IP address. These are intentionally generous since most API usage involves creating and managing entities like projects, tests, and schedules rather than high-frequency polling. You are unlikely to hit these limits during normal usage.

30 requests per second per IP address, with a burst allowance of 50 requests that are processed immediately.
10 concurrent connections per IP address.
HTTP 429 Too Many Requests is returned when you exceed the limit. If you do hit it, implement exponential backoff and retry after a short delay.

Response Format

All responses are JSON. Successful requests return a 2xx status code. Error responses include a message field describing what went wrong.

Error response

{ "message": "project not found" }

Resources

Agents

Agents are autonomous browser-based workers. Each agent gets its own browser session, receives a prompt describing what to do, and runs an agentic loop until the task is complete. Results, conversation logs, and artifacts are available via the API.

7 endpoints

Projects

Projects are containers that group together your tests, agents, schedules, and other resources. They are simple organizational buckets with no behavior of their own.

8 endpoints

Tests

Tests are re-runnable prompts. Instead of creating a new agent from scratch every time, you define a test once and run it repeatedly. Each run creates a new agent linked back to the test, giving you a history of results for the same test over time.

6 endpoints

Test Plans

Chain several tests into a directed acyclic graph (DAG): each step runs one test under a named browser profile and declares the outputs it records. Every value recorded by a step's ancestors is provided to that step's agent automatically — prompts refer to them in plain language (e.g. "log in with the credentials from the register step"), no template syntax needed. The runner walks the graph in dependency order, runs independent steps in parallel, and shares one logged-in browser across all steps that name the same profile.

12 endpoints

Schedules

Schedules automate recurring test execution. Assign tests to a schedule, set a daily run time, and the system runs them on a rotating basis, most-overdue first.

10 endpoints

Site Discovery

Discoveries automatically explore a website or Android application by spawning multiple agents across several phases. Starting from a URL (web) or an APK (Android), agents map pages/screens, forms, and interactions, then the system identifies gaps and sends agents to explore further.

6 endpoints

Mailboxes

A mailbox is a real email address your agents can read. Every message delivered to {name}@agents.aiqaramba.com is stored against the matching mailbox and exposed via the API. Attach a mailbox to a test or a test run to grant that run read access to the inbox, useful for magic links, verification codes, and signup confirmations. Mailboxes are read-only: there is no API to send mail.

5 endpoints

Roles

Roles are reusable prompt injection templates. A role's system prompt is injected into the agent's system prompt, shaping how it behaves during execution. Roles can carry attached knowledge documents (reference material) that the agent can consult while running.

9 endpoints

Findings

Findings are issues discovered by agents during test runs, discoveries, and test plans. Each finding includes severity, evidence linking back to specific agent trace steps, and triage status.

2 endpoints

Models

Models are the LLM configurations that power agents. These are managed by Aiqaramba and this endpoint lets you query which models are currently available.

1 endpoints

Recordings

Recordings capture user flows from the Aiqaramba Recorder browser extension. Each recording contains rrweb DOM events (clicks, typing, scrolling, navigation) and optionally tab video with audio. Recordings can be converted into tests for automated replay.

6 endpoints

Files

Manage tenant-scoped files that can be attached to agent runs. Upload files to your tenant store, then reference them when creating agents or running tests to copy them into the agent workspace.

6 endpoints