List actions

curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/actions?status=SUGGESTED&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"

{
  "data": [
    {
      "id": "action_01",
      "type": "SOURCE_OUTREACH",
      "category": "AUTHORITY",
      "sourceType": "SOURCE_OPPORTUNITY",
      "scope": "OFF_SITE",
      "title": "Review citation gap for Publisher Example",
      "description": "Stored answers cite this source 16 times without a SELF mention.",
      "sourceUrl": "https://publisher.example",
      "targetProvider": null,
      "evidenceProviders": ["example-provider"],
      "evidenceScope": "OBSERVED",
      "forceTier": "HIGH",
      "priorityScore": 53,
      "demandBadge": 3,
      "isQuickWin": false,
      "effort": "MEDIUM",
      "status": "SUGGESTED",
      "signals": {
        "citations": 16,
        "sourceCategory": "MEDIA",
        "competitivePressure": 2
      },
      "impactJustification": "Source cited 16x by AI answers without mentioning the brand.",
      "effortJustification": "Outreach: research the contact, pitch, and follow up.",
      "baselineMetric": null,
      "targetMetric": null,
      "questionId": null,
      "checklist": [
        "Review what content the source already cites",
        "Compare the cited pages with your existing evidence",
        "Decide whether an outreach hypothesis is worth testing",
        "Record the test and monitor later observations"
      ],
      "createdAt": "2026-06-12T05:00:00.000Z",
      "updatedAt": "2026-06-12T05:00:00.000Z"
    }
  ],
  "pagination": { "total": 42, "limit": 10, "offset": 0, "hasMore": true }
}

GET

https://www.qwairy.co

api

brands

{brandId}

actions

curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/actions?status=SUGGESTED&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"

{
  "data": [
    {
      "id": "action_01",
      "type": "SOURCE_OUTREACH",
      "category": "AUTHORITY",
      "sourceType": "SOURCE_OPPORTUNITY",
      "scope": "OFF_SITE",
      "title": "Review citation gap for Publisher Example",
      "description": "Stored answers cite this source 16 times without a SELF mention.",
      "sourceUrl": "https://publisher.example",
      "targetProvider": null,
      "evidenceProviders": ["example-provider"],
      "evidenceScope": "OBSERVED",
      "forceTier": "HIGH",
      "priorityScore": 53,
      "demandBadge": 3,
      "isQuickWin": false,
      "effort": "MEDIUM",
      "status": "SUGGESTED",
      "signals": {
        "citations": 16,
        "sourceCategory": "MEDIA",
        "competitivePressure": 2
      },
      "impactJustification": "Source cited 16x by AI answers without mentioning the brand.",
      "effortJustification": "Outreach: research the contact, pitch, and follow up.",
      "baselineMetric": null,
      "targetMetric": null,
      "questionId": null,
      "checklist": [
        "Review what content the source already cites",
        "Compare the cited pages with your existing evidence",
        "Decide whether an outreach hypothesis is worth testing",
        "Record the test and monitor later observations"
      ],
      "createdAt": "2026-06-12T05:00:00.000Z",
      "updatedAt": "2026-06-12T05:00:00.000Z"
    }
  ],
  "pagination": { "total": 42, "limit": 10, "offset": 0, "hasMore": true }
}

Returns the current Action Center queue for a brand. Scores, tiers, and quick-win flags are deterministic outputs of the Action Center’s current scoring rules; treat them as prioritization inputs, not predicted outcomes.

string

required

Bearer token. Example: Bearer qw-api-xxx

Path parameters

string

required

The unique identifier of the brand

Query parameters

string

Filter by status: SUGGESTED (awaiting triage), PENDING, IN_PROGRESS, COMPLETED, DISMISSED, RESOLVED (signal disappeared, auto-closed). Defaults to the live queue: SUGGESTED + PENDING + IN_PROGRESS.

string

Filter by action type: CONTENT_GAP, CONTENT_OPTIMIZE, TECHNICAL_FIX, SCHEMA_ADD, AUTHORITY_BUILD, SOURCE_OUTREACH, COMPETITOR_ANALYSIS, PERCEPTION_FIX, SEARCH_TARGET, SOCIAL_ENGAGE, PRODUCT_OPTIMIZE, LOCAL_OPTIMIZE

string

Filter by category: TECHNICAL, CONTENT, AEO, AUTHORITY, VISIBILITY

string

Filter by observed provider evidence. Accepts repeated or comma-separated provider IDs.

string

Filter by topic IDs. Accepts repeated or comma-separated UUIDs.

string

Filter by tag IDs. Accepts repeated or comma-separated UUIDs.

string

default:"or"

Combine selected tags with or or and.

string

Filter by TOFU, MOFU, or BOFU. Accepts repeated or comma-separated values.

string

default:"all"

Evidence period: 1, 7, 14, 30, 90, all, or custom.

string

Start date in YYYY-MM-DD format. Required with periodEnd when period=custom.

string

End date in YYYY-MM-DD format. Required with periodStart when period=custom.

number

default:"50"

Maximum number of actions to return (max: 100)

number

default:"0"

Pagination offset

Response

array

Actions ordered by priority (highest first), then creation date.

Show Action object

string

Unique identifier of the action

string

Action type (see the type filter for values)

string

Action category

string

Detector family that produced the action (e.g. PAGE_ISSUE, QUESTION_GAP, SOURCE_OPPORTUNITY, SEARCH_QUERY)

string

Nature of the work: ON_SITE, OFF_SITE or SETUP

string

Action title

string

What to do and why

string | null

External URL backing the action, when applicable

string | null

AI provider this action is scoped to (null = brand-level)

array

Provider IDs explicitly present in the underlying evidence

string

OBSERVED, CURRENT, or UNATTRIBUTED

string

Priority tier: CRITICAL, HIGH or STANDARD

number

Tier-anchored score from 0 to 100: Critical 70-100, High 40-69, and Standard 10-39. It is derived from tier, demand badge, effort, and provider scope.

number

Demand signal from 1 to 5

boolean

Whether the Action Center heuristic classifies the item as a quick win

string

Estimated workload: LOW, MEDIUM or HIGH

string

Lifecycle status

object | null

Raw quantified signals behind the priority (citations, fan-out occurrences, impressions, competitive pressure, affected pages…)

string | null

Stored explanation of the signals used for prioritization

string | null

Explanation of the estimated effort

number | null

Metric value stored when the action was created

number | null

Target metric value, when applicable

string | null

Linked monitored prompt, when applicable

array

Generated checklist associated with the action

string

ISO 8601 creation date

string

ISO 8601 last update date

object

total, limit, offset, hasMore

Synthetic request

curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/actions?status=SUGGESTED&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"

Synthetic response

{
  "data": [
    {
      "id": "action_01",
      "type": "SOURCE_OUTREACH",
      "category": "AUTHORITY",
      "sourceType": "SOURCE_OPPORTUNITY",
      "scope": "OFF_SITE",
      "title": "Review citation gap for Publisher Example",
      "description": "Stored answers cite this source 16 times without a SELF mention.",
      "sourceUrl": "https://publisher.example",
      "targetProvider": null,
      "evidenceProviders": ["example-provider"],
      "evidenceScope": "OBSERVED",
      "forceTier": "HIGH",
      "priorityScore": 53,
      "demandBadge": 3,
      "isQuickWin": false,
      "effort": "MEDIUM",
      "status": "SUGGESTED",
      "signals": {
        "citations": 16,
        "sourceCategory": "MEDIA",
        "competitivePressure": 2
      },
      "impactJustification": "Source cited 16x by AI answers without mentioning the brand.",
      "effortJustification": "Outreach: research the contact, pitch, and follow up.",
      "baselineMetric": null,
      "targetMetric": null,
      "questionId": null,
      "checklist": [
        "Review what content the source already cites",
        "Compare the cited pages with your existing evidence",
        "Decide whether an outreach hypothesis is worth testing",
        "Record the test and monitor later observations"
      ],
      "createdAt": "2026-06-12T05:00:00.000Z",
      "updatedAt": "2026-06-12T05:00:00.000Z"
    }
  ],
  "pagination": { "total": 42, "limit": 10, "offset": 0, "hasMore": true }
}

Errors

Status	Meaning
`400`	Invalid enum, taxonomy, provider, or period filter
`401`	Missing or invalid API token
`404`	Brand not found or inaccessible
`429`	Rate limit exceeded; honor `Retry-After`

See Rate limits for retry behavior.

Get started

Configure data

Monitor and measure

Analyze and act

Agency and automation

Implementation guides

Path parameters

Query parameters

Response

Synthetic request

Synthetic response

Errors

​Path parameters

​Query parameters

​Response

​Synthetic request

​Synthetic response

​Errors

Path parameters

Query parameters

Response

Synthetic request

Synthetic response

Errors