Actions API

The FloKit v1 REST API is in design-partner preview — endpoints and schemas may change before general availability. Contact your FloKit team for access.

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

string

Filter by action status. Options: draft, ready, approved, running, rolled_back. Omit to return all statuses.

integer

Number of results to return. Default: 20. Max: 100.

integer

Pagination offset. Default: 0.

Example

curl "https://YOUR-FLOKIT-API-HOST/v1/actions?status=ready&limit=20" \
  -H "Authorization: Bearer $FLOKIT_API_KEY"

Response

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

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

curl https://YOUR-FLOKIT-API-HOST/v1/actions/act_01hx4j7k9m2n3p5q6r8s \
  -H "Authorization: Bearer $FLOKIT_API_KEY"

The response includes all fields from the list endpoint plus:

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

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

curl -X POST https://YOUR-FLOKIT-API-HOST/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

string

required

Email or identifier of the person approving the action. Recorded in the audit log.

string

Optional note to record alongside the approval.

Response

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

{
  "error": "conflict",
  "message": "Action is in 'running' status and cannot be approved"
}

POST /v1/actions//reject

Reject an action and remove it from the queue.

curl -X POST https://YOUR-FLOKIT-API-HOST/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

string

required

Email or identifier of the person rejecting the action.

string

Optional reason for rejection. Recorded in the audit log.

Response

{
  "status": "ok",
  "action": {
    "id": "act_01hx4j7k9m2n3p5q6r9t",
    "status": "rejected"
  }
}

POST /v1/actions//rollback

Roll back a running or completed action.

curl -X POST https://YOUR-FLOKIT-API-HOST/v1/actions/act_01hx4j7k9m2n3p5q6r8s/rollback \
  -H "Authorization: Bearer $FLOKIT_API_KEY"

Response

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

Live endpoints

API reference

GET /v1/actions

Query parameters

Example

Response

GET /v1/actions/

POST /v1/actions//approve

Request body

Response

POST /v1/actions//reject

Request body

Response

POST /v1/actions//rollback

Response

​GET /v1/actions

​Query parameters

​Example

​Response

​GET /v1/actions/

​POST /v1/actions//approve

​Request body

​Response

​POST /v1/actions//reject

​Request body

​Response

​POST /v1/actions//rollback

​Response

GET /v1/actions

Query parameters

Example

Response

GET /v1/actions/

POST /v1/actions//approve

Request body

Response

POST /v1/actions//reject

Request body

Response

POST /v1/actions//rollback

Response