Import Test Plans API

These endpoints let you create test plans (plus the labels, credentials, and pipeline pre-steps they depend on) without the dashboard. They are the foundation of the testlab CLI and are designed for a one-shot import: point an AI agent at your existing tests, have it convert each into a plan, and push them into your account.

POST https://test-lab.ai/api/v1/test-plans
GET  https://test-lab.ai/api/v1/test-plans
POST https://test-lab.ai/api/v1/labels
GET  https://test-lab.ai/api/v1/labels
POST https://test-lab.ai/api/v1/credentials
GET  https://test-lab.ai/api/v1/credentials

Authentication

Every request uses a full-scope API key:

Authorization: Bearer tl_xxxxx

Create a key under Settings → API Keys (/admin/settings/api-keys). The key resolves to exactly one account, so the key you use IS the import target. To import into an organization account, mint the key while you have that org selected.

Create a test plan

POST /api/v1/test-plans

Imported plans are account-scoped (no project), so the target URL lives in the prompt text. That is exactly what the test-lab plan format already produces.

curl -X POST https://test-lab.ai/api/v1/test-plans \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login smoke test",
    "prompt": "Go to https://app.example.com/login and sign in with {{credentials.email}} / {{credentials.password}}. Confirm the dashboard loads.",
    "testType": "quickTest",
    "agentType": "functional",
    "labels": ["smoke", "auth"]
  }'

Response (201):

{
  "testPlan": {
    "id": 123,
    "name": "Login smoke test",
    "prompt": "Go to https://app.example.com/login …",
    "default_agent_type": "functional",
    "labels": [{ "id": 5, "name": "smoke", "color": "#22c55e" }],
    "preSteps": []
  }
}

Pipeline pre-steps

To make one plan depend on another, reference the dependency by name (resolved to the most recent plan with that name in your account) or by id:

curl -X POST https://test-lab.ai/api/v1/test-plans \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout",
    "prompt": "From the cart at https://app.example.com/cart, complete checkout.",
    "preSteps": [{ "name": "Login smoke test" }]
  }'

Create the dependency first so the name resolves. An unresolved pre-step returns 404 (the create API fails loudly rather than dropping a dependency silently). The testlab import command handles ordering for you.

List test plans

GET /api/v1/test-plans?page=1&limit=25

Returns a lean, paginated view, enough to de-duplicate before importing and to look up ids/names for pre-step wiring:

{
  "testPlans": [
    {
      "id": 123,
      "name": "Login smoke test",
      "default_agent_type": "functional",
      "labels": [{ "id": 5, "name": "smoke" }],
      "preSteps": []
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25,
  "totalPages": 1
}

Labels

POST /api/v1/labels      { "name": "smoke" }
GET  /api/v1/labels

POST is idempotent: a name that already exists returns the existing label (no error), so re-running an import is safe. You rarely need to call this directly, since POST /api/v1/test-plans auto-creates labels passed by name.

Credentials

POST /api/v1/credentials   { "key": "email", "value": "qa@example.com" }
GET  /api/v1/credentials

POST is an upsert (create, or replace the value of an existing key). Values are stored AES-256-GCM encrypted and are never returned: GET lists keys with masked values only.

curl -X POST https://test-lab.ai/api/v1/credentials \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "key": "password", "value": "hunter2" }'

A plan prompt then references it as {{credentials.password}}.

Data fixtures (test data)

Reusable, generated test data. A fixture is a named bundle of typed fields; reference a field in a prompt as {{data.<fixtureKey>.<fieldKey>}}.

POST /api/v1/data-fixtures   { "key": "...", "label"?: "...", "fields": [...] }
GET  /api/v1/data-fixtures

Each field is { key, value?, generator?, mode? }:

• static (default): a literal value (may template {{run.X}} for per-run uniqueness).
• dynamic ("mode": "dynamic"): a generator rolls a fresh value on every run. Dynamic fields require a generator.

curl -X POST https://test-lab.ai/api/v1/data-fixtures \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "newUser",
    "label": "A fresh signup",
    "fields": [
      { "key": "firstName", "mode": "dynamic", "generator": "person.firstName" },
      { "key": "email",     "mode": "dynamic", "generator": "internet.email" },
      { "key": "plan",      "mode": "static",  "value": "pro" }
    ]
  }'

A plan prompt then references it as {{data.newUser.email}}.

Generators (for dynamic fields): person.firstName, person.lastName, person.fullName, person.jobTitle, internet.email, internet.username, internet.url, internet.ipv4, phone.number, location.streetAddress, location.city, location.state, location.zipCode, location.country, company.name, lorem.word, lorem.sentence, lorem.paragraph, date.past, date.future, string.uuid, string.alphanumeric, string.numeric, number.int, boolean.

Error responses

Next steps