API Reference

Complete documentation for the Test Fire Studio REST API.

Base URL

https://api.testfirestudio.com/api/v1

Authentication

The API supports two authentication methods:

API Key (Recommended for CI/CD)

Create an API key from your dashboard and include it in the Authorization header:

Authorization: ApiKey arena_abc123...

Bearer Token (Web Application)

For browser-based applications using Clerk authentication:

Authorization: Bearer eyJhbGciOi...

Error Responses

All errors return a JSON object with an error field:

{
  "error": "Session not found",
  "code": "NOT_FOUND"
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`204`	No Content (successful deletion)
`400`	Bad Request - invalid parameters
`401`	Unauthorized - missing or invalid auth
`403`	Forbidden - account disabled
`404`	Not Found
`429`	Rate Limited
`500`	Internal Server Error

Tests (CI/CD) Recommended

                The Tests API is the recommended interface for CI/CD pipelines. It provides a simplified interface with real-time streaming, inline image uploads, and pass/fail status based on exit codes.
            

POST /tests 🔒 Auth required

Create a CI/CD test. Simplified interface that wraps sessions with streaming results.

Request Body

{
  "scenario_id": "network-validator",
  "image_id": "uuid",
  "timeout_secs": 300,
  "env_vars": {},
  "stream": true,
  "webhook_url": "https://..."
}

Response (stream: false)

{
  "id": "uuid",
  "status": "pending",
  "exit_code": null,
  "duration_ms": null,
  "artifacts": []
}

GET /tests/:id

Get test status, exit code, duration, and artifacts.

{
  "id": "uuid",
  "status": "passed",
  "exit_code": 0,
  "duration_ms": 45230,
  "started_at": "2026-01-31T12:01:00Z",
  "completed_at": "2026-01-31T12:01:45Z",
  "artifacts": [...]
}

GET /tests/:id/stream

Stream test status and logs via Server-Sent Events.

DELETE /tests/:id

Cancel a pending or running test.

Images

Images are uploaded using a two-step process: first create an image record to get a presigned URL, then upload directly to storage, and finally mark the upload as complete.

POST /images

Initiate image upload. Returns a presigned URL for uploading the image file.

{
  "name": "my-test-image",
  "description": "Custom DUT for testing",
  "arch": "amd64",
  "size_bytes": 52428800
}

GET /images

List all images for the current customer.

DELETE /images/:id

Delete an image.

Scenarios

GET /scenarios 🌐 Public

List all available test scenarios.

{
  "scenarios": [
    {
      "id": "wpa2-handshake",
      "name": "WPA2 Handshake Capture",
      "description": "Vulnerable AP for testing handshake capture",
      "category": "wifi-attacks",
      "difficulty": "beginner"
    }
  ],
  "total": 12
}

Rate Limits

Tier	Requests/min	Test creation/min
Free	60	5
Starter	300	20
Pro	600	50
Enterprise	Custom	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706702400