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.
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.
{ "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.
8 endpointsProjects
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 endpointsUser 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 endpointsSchedules
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.
9 endpointsSite Discovery
Discoveries automatically explore a website by spawning multiple agents across several phases. Starting from a URL, agents map pages, forms, and interactions, then the system identifies gaps and sends agents to explore further.
6 endpointsPersonas
Personas represent browser identities with their own credentials keychain and email inbox. Attach a persona to an agent or journey so the agent knows which credentials to use for authentication.
8 endpointsRoles
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 endpointsModels
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 endpointsProject 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 endpointsRegression 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.
1 endpointsFiles
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 endpointsGitHub
Integrate Aiqaramba with GitHub to create issues from test run findings and list accessible repositories. Requires a GitHub account to be connected via tenant settings (OAuth). When an agent discovers a bug, you can automatically generate a detailed GitHub issue with reproduction steps extracted from the agent's browser session.
2 endpointsLinear
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