Agent API Reference

BetaWindow exposes a REST API so AI agents (Cursor, Replit Agent, v0, etc.) can programmatically hire human testers without any manual steps from the developer. This is the core "AI agents hiring humans" workflow.

Authentication

All /api/v1/ endpoints use API key authentication. Generate a key in your Dashboard → API Keys.

Authorization: Bearer aqk_<your-key>

Base URL

https://betawindow.com/api/v1

Tiers & Pricing

Endpoints

List jobs

GET /api/v1/jobs?limit=20&offset=0

Returns a paginated list of test jobs you have submitted.

Response

{
  "jobs": [
    {
      "id": "uuid",
      "title": "Check checkout flow",
      "status": "completed",
      "tier": "quick",
      "price_cents": 500
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Create a job

POST /api/v1/jobs

Creates a new test job. Set auto_submit: true to immediately queue it for a human tester (skips the draft step).

Request body

{
  "title": "Test checkout flow on /checkout",
  "url": "https://my-app.vercel.app/checkout",
  "tier": "quick",
  "instructions": "Try adding an item to the cart and completing checkout. Report any errors.",
  "auto_submit": true
}

Response 201

{
  "job": {
    "id": "uuid",
    "status": "pending",
    "tier": "quick",
    "price_cents": 500
  }
}

Get job status & results

GET /api/v1/jobs/:id

Returns the job with its current status, feedback, and session info. Poll this until status === "completed".

Job status lifecycle

draft → pending → in_progress → completed
                              ↘ cancelled

Update / submit a draft

PATCH /api/v1/jobs/:id

Update fields on a draft job. To submit it for testing, set { status: "pending" }.

Cancel a job

DELETE /api/v1/jobs/:id

Cancels a draft or pending job. Has no effect once a tester has started.

Quick-start (curl)

# 1. Submit a test job
curl -X POST https://betawindow.com/api/v1/jobs \
  -H "Authorization: Bearer aqk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Smoke test homepage",
    "url": "https://my-app.vercel.app",
    "tier": "quick",
    "instructions": "Navigate the site and report any broken links or JS errors.",
    "auto_submit": true
  }'

# 2. Poll for results
curl https://betawindow.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer aqk_YOUR_KEY"

Quick-start (Python SDK)

import httpx, time

API_KEY = "aqk_YOUR_KEY"
BASE = "https://betawindow.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Submit
resp = httpx.post(f"{BASE}/jobs", headers=HEADERS, json={
    "title": "Smoke test homepage",
    "url": "https://my-app.vercel.app",
    "tier": "quick",
    "auto_submit": True,
})
job = resp.json()["job"]
print(f"Job {job['id']} submitted")

# Poll until done
while job["status"] not in ("completed", "cancelled"):
    time.sleep(30)
    job = httpx.get(f"{BASE}/jobs/{job['id']}", headers=HEADERS).json()["job"]

print("Feedback:", job.get("feedback"))

Rate limits

50 requests / minute per API key. Exceeding returns 429 Too Many Requests.

Errors

All errors return JSON with an error field and a standard HTTP status code.

{
  "error": "title and url are required"
}