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

# Labels API

> Create, manage, and run tests by label programmatically

Labels organize your flows and suites and let you run groups of tests by name (e.g. `smoke`, `checkout`, `regression`). These endpoints manage labels, attach them to flows and suites, and trigger runs by label — useful for CI pipelines that run a subset of tests per branch or PR.

All requests require an API key in the `X-API-Key` header. See [API Reference](/api-reference) for authentication and the standard `401` / `403` / `429` / `500` error shapes shared by every endpoint on this page.

<Note>
  Labels are also managed in the [dashboard](https://autosana.ai/settings?tab=labels) (Settings → Labels, and inline on any flow or suite). The dashboard uses your signed-in session; this API is for programmatic and CI use with an organization API key.
</Note>

***

## List Labels

Returns every label in your organization, ordered by name.

<Note>
  **GET** `/api/v1/labels` — Returns `200 OK`
</Note>

### Example Request

```bash theme={null}
curl -X GET "https://backend.autosana.ai/api/v1/labels" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response Fields

<ResponseField name="labels" type="array">
  List of label objects.

  <Expandable title="Label object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID).
    </ResponseField>

    <ResponseField name="name" type="string">
      Label name (unique per organization, case-insensitive).
    </ResponseField>

    <ResponseField name="color" type="string">
      Hex color used to render the label (e.g. `"#4cb782"`).
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="flow_count" type="integer">
      Number of active flows carrying this label.
    </ResponseField>

    <ResponseField name="suite_count" type="integer">
      Number of active suites carrying this label.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of labels returned.
</ResponseField>

#### Example Response

```json theme={null}
{
  "labels": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440001",
      "name": "smoke",
      "color": "#4cb782",
      "created_at": "2026-01-15T10:30:00Z",
      "flow_count": 12,
      "suite_count": 2
    },
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440002",
      "name": "checkout",
      "color": "#5e6ad2",
      "created_at": "2026-01-16T09:00:00Z",
      "flow_count": 4,
      "suite_count": 1
    }
  ],
  "count": 2
}
```

***

## Create Label

<Note>
  **POST** `/api/v1/labels` — Returns `201 Created`. Returns `409 Conflict` if a label with the same `name` already exists (names are unique per organization, case-insensitive).
</Note>

### Request Body

<ParamField body="name" type="string" required>
  Label name (1–255 characters). Must be unique within your organization.
</ParamField>

<ParamField body="color" type="string">
  Optional hex color (e.g. `"#eb5757"`). Defaults to a stable color derived from the name.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST https://backend.autosana.ai/api/v1/labels \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "smoke", "color": "#4cb782" }'
```

#### Example Response

```json theme={null}
{
  "id": "aa0e8400-e29b-41d4-a716-446655440001",
  "name": "smoke",
  "color": "#4cb782",
  "created_at": "2026-01-15T10:30:00Z"
}
```

***

## Get Label

<Note>
  **GET** `/api/v1/labels/{label_id}` — Returns `200 OK` with the same shape as items in [List Labels](#list-labels), or `404` if the label does not exist.
</Note>

<ParamField path="label_id" type="string" required>
  UUID of the label.
</ParamField>

```bash theme={null}
curl -X GET https://backend.autosana.ai/api/v1/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Update Label

Rename or recolor a label. Only provided fields change; omitted fields are unchanged.

<Note>
  **PATCH** `/api/v1/labels/{label_id}` — Returns `200 OK`. `400` if no recognized fields are provided. `404` if the label does not exist. `409` if renaming collides with another label.
</Note>

<ParamField path="label_id" type="string" required>
  UUID of the label.
</ParamField>

<ParamField body="name" type="string">
  New name (1–255 characters).
</ParamField>

<ParamField body="color" type="string">
  New hex color.
</ParamField>

<Warning>
  Renaming a label affects [runs by label](#run-by-label) and the CI `labels` input, which match on name — update any workflows that reference the old name.
</Warning>

```bash theme={null}
curl -X PATCH https://backend.autosana.ai/api/v1/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "smoke-tests", "color": "#26b5ce" }'
```

***

## Delete Label

Deletes the label and removes it from every flow and suite it's attached to.

<Note>
  **DELETE** `/api/v1/labels/{label_id}` — Returns `204 No Content`, or `404` if the label does not exist.
</Note>

<ParamField path="label_id" type="string" required>
  UUID of the label.
</ParamField>

```bash theme={null}
curl -X DELETE https://backend.autosana.ai/api/v1/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Attach & Detach Labels

Attach or detach a single label to a flow or suite. There is no bulk endpoint — issue one call per (entity, label) pair.

### Attach to a flow

<Note>
  **POST** `/api/v1/flows/{flow_id}/labels/{label_id}` — Returns `201 Created`. `404` if the flow or label does not exist. `409` if the label is already attached.
</Note>

```bash theme={null}
curl -X POST https://backend.autosana.ai/api/v1/flows/FLOW_UUID/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

### Detach from a flow

<Note>
  **DELETE** `/api/v1/flows/{flow_id}/labels/{label_id}` — Returns `204 No Content`. `404` if the label is not attached to the flow.
</Note>

```bash theme={null}
curl -X DELETE https://backend.autosana.ai/api/v1/flows/FLOW_UUID/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

### Attach to / detach from a suite

Same shape, with `/suites/{suite_id}` instead of `/flows/{flow_id}`:

```bash theme={null}
# Attach
curl -X POST https://backend.autosana.ai/api/v1/suites/SUITE_UUID/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY"

# Detach
curl -X DELETE https://backend.autosana.ai/api/v1/suites/SUITE_UUID/labels/LABEL_UUID \
  -H "X-API-Key: YOUR_API_KEY"
```

***

## Run by Label

Trigger a run of everything carrying one or more labels by passing `labels` (label **names**) to the [Runs API](/api-runs#run-flows). Autosana runs the union of the suites and flows that carry any of those labels; a flow already covered by a matched suite runs once. As with any run, provide `app_id` (web) or `bundle_id` + `platform` (mobile). A request whose labels match nothing returns `400`.

<Note>
  **POST** `/api/v1/flows/run` — Returns `200 OK` with a `batch_id` to poll via [Run Status](/api-runs#run-status).
</Note>

```bash theme={null}
curl -X POST https://backend.autosana.ai/api/v1/flows/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "labels": ["smoke", "checkout"]
  }'
```

See the [Runs API](/api-runs) for the full request body, polling, and result shapes.

***

## CI Usage

In CI, the simplest entry point is the [autosana-ci GitHub Action](/ci-cd-integration) — pass a comma-separated `labels` input to run the matching suites and flows after your build is uploaded, instead of listing `suite-ids` / `flow-ids`:

```yaml theme={null}
- uses: autosana/autosana-ci@main
  with:
    api-key: ${{ secrets.AUTOSANA_KEY }}
    bundle-id: com.company.app
    platform: android
    build-path: app.apk
    labels: smoke,checkout  # run everything carrying any of these labels
```

See [CI/CD Integration](/ci-cd-integration) for the full workflow setup.