> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API for test automation, workflows, and builds

## Base URLs

Revyl provides a unified REST API:

| Service         | Base URL                   | Purpose                                                |
| --------------- | -------------------------- | ------------------------------------------------------ |
| **Backend API** | `https://backend.revyl.ai` | Tests, builds, workflows, execution, device management |

<Tip>
  All API endpoints are available through the **Backend API** at `backend.revyl.ai`.
</Tip>

## Authentication

All API requests require a Bearer token in the Authorization header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://backend.revyl.ai/api/v1/apps
```

See [Authentication](/api-reference/authentication) for details on creating and managing API keys.

## Quick Reference

For end-to-end request examples, see [API Quickstart](/api-reference/quickstart).

### Test Execution (Backend API)

| Method | Endpoint                                                  | Description               |
| ------ | --------------------------------------------------------- | ------------------------- |
| POST   | `/api/v1/execution/api/execute_test_id_async`             | Execute a test            |
| GET    | `/api/v1/tests/get_test_execution_task?task_id={task_id}` | Get test execution status |
| POST   | `/api/v1/execution/tests/status/cancel/{task_id}`         | Cancel running test       |

### Workflow Execution (Backend API)

| Method | Endpoint                                          | Description        |
| ------ | ------------------------------------------------- | ------------------ |
| POST   | `/api/v1/execution/api/execute_workflow_id_async` | Execute a workflow |

### Workflow Status (Backend API)

| Method | Endpoint                                    | Description                    |
| ------ | ------------------------------------------- | ------------------------------ |
| GET    | `/api/v1/workflows/status/status/{task_id}` | Get workflow execution status  |
| GET    | `/api/v1/workflows/history/{workflow_id}`   | Get workflow execution history |

### Builds (Backend API)

| Method | Endpoint                                     | Description            |
| ------ | -------------------------------------------- | ---------------------- |
| GET    | `/api/v1/apps`                               | List apps              |
| POST   | `/api/v1/apps`                               | Create app             |
| GET    | `/api/v1/apps/{app_id}`                      | Get app                |
| PATCH  | `/api/v1/apps/{app_id}`                      | Update app             |
| DELETE | `/api/v1/apps/{app_id}`                      | Delete app             |
| POST   | `/api/v1/apps/{app_id}/builds/stream-upload` | Stream upload build    |
| POST   | `/api/v1/apps/{app_id}/builds/upload-url`    | Create upload URL      |
| POST   | `/api/v1/apps/{app_id}/builds/from-url`      | Create from remote URL |
| GET    | `/api/v1/apps/{app_id}/builds`               | List builds            |
| GET    | `/api/v1/apps/builds/{build_id}`             | Get build              |
| PATCH  | `/api/v1/apps/builds/{build_id}`             | Update build           |
| DELETE | `/api/v1/apps/builds/{build_id}`             | Delete build           |

### YAML Operations (Backend API)

| Method | Endpoint                                 | Description             |
| ------ | ---------------------------------------- | ----------------------- |
| POST   | `/api/v1/yaml/from-yaml`                 | Create test from YAML   |
| POST   | `/api/v1/yaml/from-blocks`               | Create test from blocks |
| POST   | `/api/v1/yaml/validate-yaml`             | Validate YAML           |
| POST   | `/api/v1/yaml/conversion/blocks-to-yaml` | Convert blocks to YAML  |
| POST   | `/api/v1/yaml/conversion/yaml-to-blocks` | Convert YAML to blocks  |

### Monitoring (Backend API)

| Method | Endpoint                         | Description                    |
| ------ | -------------------------------- | ------------------------------ |
| GET    | `/api/v1/monitor/stream/unified` | Stream real-time updates (SSE) |

## Response Format

### Success Response

```json theme={null}
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Operation successful"
}
```

### Error Response

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

## Status Codes

| Code | Description                              |
| ---- | ---------------------------------------- |
| 200  | Success                                  |
| 400  | Bad request (invalid parameters)         |
| 401  | Unauthorized (invalid API key)           |
| 403  | Forbidden (insufficient permissions)     |
| 404  | Resource not found                       |
| 409  | Conflict (duplicate resource)            |
| 422  | Unprocessable entity (validation failed) |
| 500  | Server error                             |
| 502  | Bad gateway (upstream service error)     |
| 503  | Service unavailable                      |

## OpenAPI Specifications

Full OpenAPI specifications are available at:

* **Backend API**: `https://backend.revyl.ai/openapi.json`

These specifications power the interactive playground in this documentation.