Skip to main content
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 for authentication and the standard 401 / 403 / 429 / 500 error shapes shared by every endpoint on this page.
Labels are also managed in the dashboard (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.

​
List Labels

Returns every label in your organization, ordered by name.
GET /api/v1/labels — Returns 200 OK

​
Example Request

curl -X GET "https://backend.autosana.ai/api/v1/labels" \
  -H "X-API-Key: YOUR_API_KEY"

​
Response Fields

​
labels
array
List of label objects.
​
count
integer
Total number of labels returned.

​
Example Response

{
  "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

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).

​
Request Body

​
name
string
required
Label name (1–255 characters). Must be unique within your organization.
​
color
string
Optional hex color (e.g. "#eb5757"). Defaults to a stable color derived from the name.

​
Example Request

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

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

​
Get Label

GET /api/v1/labels/{label_id} — Returns 200 OK with the same shape as items in List Labels, or 404 if the label does not exist.
​
label_id
string
required
UUID of the label.
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.
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.
​
label_id
string
required
UUID of the label.
​
name
string
New name (1–255 characters).
​
color
string
New hex color.
Renaming a label affects runs by label and the CI labels input, which match on name — update any workflows that reference the old name.
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.
DELETE /api/v1/labels/{label_id} — Returns 204 No Content, or 404 if the label does not exist.
​
label_id
string
required
UUID of the label.
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

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.
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

DELETE /api/v1/flows/{flow_id}/labels/{label_id} — Returns 204 No Content. 404 if the label is not attached to the flow.
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}: 
# 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. 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.
POST /api/v1/flows/run — Returns 200 OK with a batch_id to poll via Run Status.
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 for the full request body, polling, and result shapes.

​
CI Usage

In CI, the simplest entry point is the autosana-ci GitHub Action — 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: 
- 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 for the full workflow setup.