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

# API Reference Overview

> Programmatically trigger flow executions, manage suites, and query platform analytics.

The Quixa REST API allows developers, DevOps pipelines, and automation bots to interact with all platform resources programmatically.

***

## 1. Authentication

Quixa supports dual enterprise authentication methods: **OAuth2 Client Credentials Grant** for machine-to-machine (M2M) workloads and **Direct API Key Headers** for automated pipelines and trial access.

### 1.1. OAuth2 Client Credentials Flow (`/oauth/token`)

Exchange your `client_id` and `client_secret` for a high-performance scoped JWT Bearer token:

```bash theme={null}
curl -X POST "https://api.quixa.io/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=acme-workflow-sync" \
  -d "client_secret=qxa_live_YOUR_CLIENT_SECRET"
```

Response:

```json theme={null}
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "flows:read flows:write executions:run"
}
```

### 1.2. Direct API Key Header (`X-API-Key`)

Pass your secret key directly in the `X-API-Key` HTTP header:

```bash theme={null}
curl -X GET "https://api.quixa.io/api/gateway/flows" \
  -H "X-API-Key: qxa_live_YOUR_CLIENT_SECRET"
```

### 1.3. Developer Trial Keys & Zero-Downtime Rotation

* **14-Day Developer Trials**: Temporary sandbox credentials with automatic expiration (`ExpiresAt = UtcNow + 14d`).
* **Zero-Downtime Secret Rotation**: When rotating credentials via the Backoffice, previous secrets remain operational during a **24-hour grace period**, ensuring zero downtime across active production services.
* **Backoffice Management**: Provision, rotate, and revoke clients under **Backoffice** -> **API Keys & Clients**.

***

## 2. Core Endpoint Summary

| Category | Method & Endpoint | Description |
| :- | :- | :- |
| **Flows** | `GET /api/gateway/flows` | List all flows in tenant workspace. |
| **Flows** | `GET /api/gateway/flows/{id}` | Retrieve flow DAG structure and node configurations. |
| **Execution** | `POST /api/gateway/flows/{id}/run` | Trigger immediate visual workflow execution. |
| **Execution** | `GET /api/gateway/executions/{id}` | Retrieve execution trace history, status, and latencies. |
| **Suites** | `GET /api/gateway/suites` | List all registered Flow & Test Suites. |
| **Suites** | `POST /api/gateway/suites/{id}/run` | Trigger CI/CD suite execution pipeline. |
| **Schedules** | `GET /api/schedules` | List active Hangfire cron execution schedules. |

***

## 3. Standard Response Format

All successful responses return structured JSON:

```json theme={null}
{
  "success": true,
  "data": {
    "executionId": "f7a1c8b2-5e4d-4911-82ab-0e927c3d10fa",
    "status": "Completed",
    "durationMs": 412,
    "nodesExecuted": 8,
    "nodesSkipped": 2
  }
}
```

In the event of an error:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FLOW_NOT_FOUND",
    "message": "Workflow with ID '...' could not be resolved in the active tenant."
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.