API Reference

The Aiqaramba API gives you full programmatic access to everything the platform can do. Create projects, define journeys, 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 journeys 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, journeys, 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 journeys, agents, schedules, and other resources. They are simple organizational buckets with no behavior of their own.
8 endpoints
User Journeys
Journeys are re-runnable prompts. Instead of creating a new agent from scratch every time, you define a journey once and run it repeatedly. Each run creates a new agent linked back to the journey, giving you a history of results for the same test over time.
6 endpoints
Test Plans
Test plans string multiple user journeys into a directed acyclic graph (DAG). Each step runs a journey under a named browser profile, declares the outputs it records, and binds inputs from earlier steps' outputs or plan-level variables.
12 endpoints
Schedules
Schedules automate recurring journey execution. Assign journeys to a schedule, set a frequency, and the system runs them on a rotating basis within your agent budget.
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 journey 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 description is injected into the agent's system prompt, shaping how it behaves during execution.
4 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
Project Memories
Project-scoped knowledge base that agents build up over time. Agents save operational insights during execution that future agents on the same project can recall via full-text search.
5 endpoints
Regression Testing
Automatically determine which test journeys to run based on code changes. The regression endpoint analyzes commit messages, PR descriptions, and file diffs against your project's app map and journey catalog using an LLM, then triggers the matched journeys as regression tests. Designed for CI/CD integration — call this after every deploy to run only the tests that matter. At most 5 journeys are triggered per call; if the LLM matches more, only the highest-ranked five run. 

**When no journey matches** the changes (or the matcher flags a coverage gap), the endpoint also tries to *auto-generate* a fresh journey from the commit context and either the project's app map (if a discovery has completed) or the project's entry URL (if no discovery exists yet — discovery is expensive and most teams won't run it on every release cadence). The generated journey is exploratory in the no-map case but better than nothing for the "we shipped a new surface and there's no journey for it" case. The response's `auto_journey_status` field surfaces what the auto-generation step did so CI can render a meaningful summary instead of an empty result.
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 user journeys 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 journeys to copy them into the agent workspace.
6 endpoints
Linear
Integrate Aiqaramba with Linear to sync issues as user journeys and post test run results back as comments. See the CI/CD integration guide for the full setup walkthrough.
3 endpoints