Agentic Plans API

The agentic plans API is the read-only HTTP layer over the agentic-superpowers pipeline (brainstorm → plan → execute). Plans are created and mutated exclusively by the master agent through its pipeline tools (build_plan, complete_step, fail_step, skip_step, complete_plan, clarify_intent) — the HTTP API only allows inspection. Full module documentation: Agentic Chat.

All endpoints Sanctum-authenticated, team-scoped, policy: view only.

Endpoints

Plan response

{
  "data": {
    "id": 12,
    "session_id": 42,
    "goal": "Competitor analysis example.com",
    "brainstorm_summary": null,
    "strategy": "linear",
    "status": "executing",
    "current_step_id": 35,
    "total_steps": 4,
    "completed_steps": 1,
    "failed_steps": 0,
    "started_at": "2026-05-01T08:30:00Z",
    "completed_at": null,
    "total_tool_calls": 9,
    "total_credits_used": 5,
    "created_at": "2026-05-01T08:29:55Z"
  }
}

Plan status values: planning | executing | completed | failed | aborted. Strategy values: linear (default) — steps strictly sequential.

Steps response

{
  "data": [
    {
      "id": 35,
      "step_index": 0,
      "label": "Identify top-10 SERP competitors",
      "description": "...",
      "complexity": "trivial",
      "assigned_agent": null,
      "status": "completed",
      "retry_count": 0,
      "last_error": null,
      "output_summary": "10 competitors: ahrefs.com, semrush.com, ...",
      "output_data": { "competitors": ["ahrefs.com", "..."] },
      "tool_calls_made": 1,
      "credits_used": 1,
      "latency_ms": 3120,
      "subagent_session_id": null,
      "started_at": "2026-05-01T08:30:01Z",
      "completed_at": "2026-05-01T08:30:04Z"
    }
  ]
}

Step status values: pending | in_progress | completed | failed | skipped. assigned_agent values: null (master itself) | master | analyze | explore | research | action. output_data limit: ≤ 64 kB JSON. Larger outputs are truncated and surfaced as output_summary.

Polling pattern

The master agent drives execution internally. Frontends poll the plan to keep the UI stream in sync.

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PLAN=12

while true; do
  R=$(curl -s -H "Authorization: Bearer $TOKEN" "$BASE/agentic/plans/$PLAN")
  STATUS=$(echo "$R" | jq -r '.data.status')
  DONE=$(echo "$R"   | jq -r '.data.completed_steps')
  TOTAL=$(echo "$R"  | jq -r '.data.total_steps')
  echo "[$STATUS] $DONE / $TOTAL steps"
  case "$STATUS" in
    completed|failed|aborted) break ;;
  esac
  sleep 2
done

# Fetch output of all steps
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/agentic/plans/$PLAN/steps" \
  | jq '.data[] | {step_index, label, status, output_summary}'

Retry / abort

There are no HTTP endpoints for retry or abort. Mutations happen exclusively through the master agent's internal pipeline tools:

• Retry of a step — the master agent calls fail_step, the pipeline manager redispatches the step. Over HTTP only observable via retry_count and last_error.
• Abort of a plan — the user sends an abort intent in chat ("stop", "cancel") → master agent calls abort_plan → status: aborted.
• Skip a step — master agent calls skip_step with a reason — step remains in the log with status: skipped.

External clients that need abort behavior send the intent as a user message through the chat-send API; the master agent translates that into abort_plan.

Status codes

Pitfalls

• No mutation endpoints. PATCH/DELETE on /v1/agentic/plans/* is intentionally not implemented — the master agent is the writer.
• output_data is truncated. For large JSON outputs (> 64 kB) the field is shortened; full outputs are only available through the session's tool-call log.
• subagent_session_id is set only for subagent steps. Master-owned steps have null — to read the subagent trace, follow the session ID into /v1/agentic/sessions/{id}.
• Polling frequency. 2 s is fine for live UIs; for many parallel plans use server-sent events or the chat-stream API instead.

Related: Agentic Chat · Chat Shares API · Credits API.