Run a Priority Analysis

This guide walks you through running an AI Eisenhower-Matrix burnout analysis on the open bits of one of your chainies. It is two HTTP calls: one to consume your daily quota and create the AI session, another to start the run.

For background on what the feature does and which plans include it, see Priority Analysis.

---

Prerequisites

• An active subscription on Bitter, Chainer, or Architect (Free has a zero quota and will return 403 QUOTA_EXCEEDED).
• A JWT bearer token for the chainer who owns the chainy.
• The chainy_id of the chainy you want to analyse.

---

Step 1 — Create the run

curl -X POST 'https://api.chainabit.com/productivity/priority-analysis/runs' \
  -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  -d '{
    "chainyId": "0e85ad6a-d3a1-4c2b-8b48-1f9b40b6e3e1",
    "mode": "approval",
    "effortMode": "thinking"
  }'

A successful response looks like this:

{
  "data": {
    "sessionId": "9ad5a9b6-1c41-4f65-9f3b-2c2bbeeac16e",
    "mode": "approval",
    "chainyId": "0e85ad6a-d3a1-4c2b-8b48-1f9b40b6e3e1",
    "scope": "chainy",
    "featureKey": "productivity.analysis.priority",
    "toolDomains": [
      "bits.query","bits.get","bits.reprioritize","bits.update","bits.delete"
    ],
    "quota": { "used": 1, "limit": 2, "remaining": 1, "periodUnit": "daily" },
    "seedMessage": {
      "content": "Run a priority analysis on \"Ship the launch\".\nChainy vision: \"Help focused people get unstuck\"\n\nUser local datetime: 2026-05-27T18:50:16 (Europe/Istanbul)\nOpen bits in scope: 72\n\nAggregate stats over the full open-bit set:\n- by priority: p1=0, p2=5, p3=3, p4=0, unset=64\n- schedule: scheduled=19 (overdue=3), unscheduled=53\n- age: fresh(≤7d)=4, stale(8–30d)=23, ancient(>30d)=45, oldest=68d\n\nCurated hint (10 of 72 highest-ranked bits — the remaining 62 must be discovered via bits.query):\n…\n\nDiscover bits with `bits.query` before proposing any change. …"
    },
    "accountTimezone": "Europe/Istanbul"
  }
}

The seedMessage.content field is the first user message you should send to start the AI run. It is intentionally small (a few hundred bytes to a couple of KB) and well below the 20,000-character cap of POST /ai/sessions/:sessionId/messages — the Priority Analyst agent fetches the bits it needs through bits.query and bits.get once the run starts, so the seed never enumerates them.

Picking a mode

mode	Behaviour
approval	The AI proposes one batched bits.reprioritize change set; you approve from the standard Chao approval card.
auto	The AI applies the proposed changes immediately.
plan	The AI writes the proposed changes to your active plan; nothing is mutated.

Picking a model

You have two options:

• model — pass an exact ai.models.model_key (for example gemini-2.5-pro). Only models you are entitled to are accepted.
• effortMode — basic, thinking, or pro. The orchestrator picks a compatible model that you are entitled to. This is the recommended path.

---

Step 2 — Start the run

Post the seed message returned by Step 1 to the standard AI session endpoint:

curl -X POST "https://api.chainabit.com/ai/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  -d "{ \"content\": $(jq -Rs '.' <<< \"$SEED_CONTENT\") }"

Open the SSE stream as you would for any Chao session:

const events = new EventSource(
  `https://api.chainabit.com/ai/sessions/${sessionId}/stream`,
  { withCredentials: true },
);

events.addEventListener('tool.approval_required', (e) => {
  const payload = JSON.parse(e.data);
  // { toolKey: 'bits.reprioritize', input: { updates: [...], reason: '...' } }
  // → render approval card
});

events.addEventListener('tool.completed', (e) => {
  const payload = JSON.parse(e.data);
  // { updatedCount, failedCount, updated, failed, reason }
});

events.addEventListener('run.completed', () => {
  events.close();
});

In approval mode the AI pauses on tool.approval_required until you call the existing approval endpoint. In auto mode the change set is applied immediately and you only see tool.completed. In plan mode you will instead see plan.step_added events and no mutation.

---

Common errors

HTTP	code	What it means
403	QUOTA_EXCEEDED	You have used your daily allowance for this chainy. The counter resets at midnight in your account timezone.
403	ENTITLEMENT_MISSING	Your plan does not include productivity.analysis.priority.
403	SUBSCRIPTION_REQUIRED	No active subscription was found for the chainer or account.
404	CHAINY_NOT_FOUND	The chainy id does not belong to your chainer.
404	MODEL_NOT_AVAILABLE	The model you requested is not active or you are not entitled to it.

---

Tips

• The Priority Analyst is told to make a single bits.reprioritize call covering every bit it wants to change. You will normally see one approval card, not many.
• The agent only proposes deletions for bits it considers clear P4 trash, capped at five per run.
• Completed bits are excluded from the candidate set — re-run the analysis after completing items to see how your cognitive load shifts.
• The daily counter is per-chainy, so running an analysis on chainy A does not consume budget for chainy B.
• Expect to see a few bits.query calls before the final bits.reprioritize in the SSE stream — that is the agent paginating through your bits to ground its decision.