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

# Actions API

> List, review, and approve growth actions.

FloKit surfaces recommended growth actions — budget shifts, creative pauses, offer experiments — based on payback and cohort signal. The Actions API lets you integrate action review into your own workflows, Slack bots, or approval tools.

Available during private beta — contact FloKit for access.

***

## GET /v1/actions

List actions in the workspace action queue.

### Query parameters

<ParamField query="status" type="string">
  Filter by action status. Options: `draft`, `ready`, `approved`, `running`, `rolled_back`. Omit to return all statuses.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results to return. Default: `20`. Max: `100`.
</ParamField>

<ParamField query="offset" type="integer">
  Pagination offset. Default: `0`.
</ParamField>

### Example

```bash theme={null}
curl "https://api.flokit.ai/v1/actions?status=ready&limit=20" \
  -H "Authorization: Bearer $FLOKIT_API_KEY"
```

### Response

```json theme={null}
{
  "actions": [
    {
      "id": "act_01hx4j7k9m2n3p5q6r8s",
      "type": "budget_shift",
      "status": "ready",
      "title": "Shift 20% budget from TikTok Broad to Meta Search",
      "rationale": "Meta Search cohort (Jan) reached payback in 16 days vs. TikTok Broad at 34 days. Reallocating $4,400/week is projected to improve blended ROAS by 0.3x.",
      "expected_impact": {
        "metric": "blended_roas_30d",
        "direction": "increase",
        "magnitude": 0.3
      },
      "created_at": "2024-03-15T06:00:00Z",
      "approved_at": null,
      "approved_by": null
    },
    {
      "id": "act_01hx4j7k9m2n3p5q6r9t",
      "type": "creative_pause",
      "status": "ready",
      "title": "Pause creative TK_VID_042 — fatigue detected",
      "rationale": "Creative TK_VID_042 has served 1.2M impressions in 8 days. CTR has declined 61% from launch. Trial conversion for this creative is now below the campaign floor (0.48 vs. 0.65 floor).",
      "expected_impact": {
        "metric": "campaign_trial_conversion_rate",
        "direction": "increase",
        "magnitude": 0.06
      },
      "created_at": "2024-03-15T06:00:00Z",
      "approved_at": null,
      "approved_by": null
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}
```

***

## GET /v1/actions/{id}

Get a single action with full detail: data signals, guardrail checks, and rollback conditions.

```bash theme={null}
curl https://api.flokit.ai/v1/actions/act_01hx4j7k9m2n3p5q6r8s \
  -H "Authorization: Bearer $FLOKIT_API_KEY"
```

The response includes all fields from the list endpoint plus:

```json theme={null}
{
  "action": {
    "id": "act_01hx4j7k9m2n3p5q6r8s",
    "type": "budget_shift",
    "status": "ready",
    "title": "Shift 20% budget from TikTok Broad to Meta Search",
    "rationale": "...",
    "expected_impact": { "metric": "blended_roas_30d", "direction": "increase", "magnitude": 0.3 },
    "created_at": "2024-03-15T06:00:00Z",
    "approved_at": null,
    "approved_by": null,
    "data_signals": [
      { "label": "Meta Search 30-day ROAS", "value": "2.31x" },
      { "label": "TikTok Broad 30-day ROAS", "value": "0.91x" },
      { "label": "Meta Search payback days", "value": "16" },
      { "label": "TikTok Broad payback days", "value": "34" }
    ],
    "guardrail_checks": [
      { "check": "minimum_cohort_size", "passed": true, "detail": "Meta Search cohort n=1,989" },
      { "check": "statistical_confidence", "passed": true, "detail": "95% confidence in ROAS delta" },
      { "check": "spend_change_within_limit", "passed": true, "detail": "Shift is 20% of campaign budget" }
    ],
    "rollback_conditions": [
      "If blended ROAS drops >15% within 7 days of execution",
      "If Meta Search trial conversion rate falls below 0.65"
    ]
  }
}
```

***

## POST /v1/actions/{id}/approve

Approve an action for execution. Only actions in `ready` status can be approved.

```bash theme={null}
curl -X POST https://api.flokit.ai/v1/actions/act_01hx4j7k9m2n3p5q6r8s/approve \
  -H "Authorization: Bearer $FLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approved_by": "user@yourteam.com",
    "note": "Looks good — Q1 budget shift aligned with our channel strategy"
  }'
```

### Request body

<ParamField body="approved_by" type="string" required>
  Email or identifier of the person approving the action. Recorded in the audit log.
</ParamField>

<ParamField body="note" type="string">
  Optional note to record alongside the approval.
</ParamField>

### Response

```json theme={null}
{
  "status": "ok",
  "action": {
    "id": "act_01hx4j7k9m2n3p5q6r8s",
    "status": "approved",
    "approved_at": "2024-03-15T14:30:00Z",
    "approved_by": "user@yourteam.com"
  }
}
```

Returns `409 Conflict` if the action is not in `ready` status:

```json theme={null}
{
  "error": "conflict",
  "message": "Action is in 'running' status and cannot be approved"
}
```

***

## POST /v1/actions/{id}/reject

Reject an action and remove it from the queue.

```bash theme={null}
curl -X POST https://api.flokit.ai/v1/actions/act_01hx4j7k9m2n3p5q6r9t/reject \
  -H "Authorization: Bearer $FLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rejected_by": "user@yourteam.com",
    "reason": "We are running a creative refresh next week — holding off on pausing this creative"
  }'
```

### Request body

<ParamField body="rejected_by" type="string" required>
  Email or identifier of the person rejecting the action.
</ParamField>

<ParamField body="reason" type="string">
  Optional reason for rejection. Recorded in the audit log.
</ParamField>

### Response

```json theme={null}
{
  "status": "ok",
  "action": {
    "id": "act_01hx4j7k9m2n3p5q6r9t",
    "status": "rejected"
  }
}
```

***

## POST /v1/actions/{id}/rollback

Roll back a running or completed action.

```bash theme={null}
curl -X POST https://api.flokit.ai/v1/actions/act_01hx4j7k9m2n3p5q6r8s/rollback \
  -H "Authorization: Bearer $FLOKIT_API_KEY"
```

### Response

```json theme={null}
{
  "status": "ok",
  "action": {
    "id": "act_01hx4j7k9m2n3p5q6r8s",
    "status": "rolled_back"
  }
}
```

Rollback availability depends on the action type. Budget shifts and creative pauses can be rolled back. Actions that rely on third-party platform changes may have a short propagation delay before the rollback takes effect.