Quick Start

Get a ranked sequence in one API call. No SDK needed — just curl.

curl -X POST https://advanseq.replit.app/v1/sequence \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weight_profile": "activation",
    "items": [
      {"id": "task-1", "label": "Fix login bug",    "urgency": 0.9, "impact": 0.8, "effort": 0.3, "dependency_count": 0},
      {"id": "task-2", "label": "Add dark mode",     "urgency": 0.2, "impact": 0.5, "effort": 0.6, "dependency_count": 0},
      {"id": "task-3", "label": "Upgrade database",  "urgency": 0.7, "impact": 0.9, "effort": 0.8, "dependency_count": 2},
      {"id": "task-4", "label": "Write API docs",    "urgency": 0.5, "impact": 0.6, "effort": 0.4, "dependency_count": 1}
    ]
  }'

Response:

{
  "job_id": "8f2a1c3d-...",
  "weight_profile": "activation",
  "sequence": [
    {"item_id": "task-1", "label": "Fix login bug",   "rank": 1, "score": 0.823},
    {"item_id": "task-3", "label": "Upgrade database", "rank": 2, "score": 0.761},
    {"item_id": "task-4", "label": "Write API docs",   "rank": 3, "score": 0.512},
    {"item_id": "task-2", "label": "Add dark mode",    "rank": 4, "score": 0.347}
  ],
  "calibration_questions": [
    {
      "question_id": "q_7d3e...",
      "prompt": "These two items scored within 2.5% — which would you prioritize?",
      "option_a": {"item_id": "task-3", "label": "Upgrade database", "score": 0.761},
      "option_b": {"item_id": "task-4", "label": "Write API docs",  "score": 0.738}
    }
  ]
}

Don't have an API key? Create a free account — takes 30 seconds.

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer ask_04Z-wDrw...

Your API key starts with ask_. Keep it secret — it authenticates all requests to your tenant.

POST /v1/sequence

The core endpoint. Send items with numeric dimension scores and a weight profile — get back a ranked sequence.

Request body

4-phase pipeline

1. Normalize — min-max scale all dimensions to [0, 1]
2. Resolve — topological sort by depends_on constraints (Kahn's algorithm)
3. Score — weighted dot-product: score = Σ(normalized_dim × weight)
4. Calibrate — detect near-ties, generate Either/Or questions for human tiebreaking

Item Constraints

Filter, pin, and adjust items before and after scoring. All constraint fields are optional on POST /v1/sequence.

curl -X POST https://advanseq.replit.app/v1/sequence \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weight_profile": "activation",
    "constraints": {
      "exclude_ids": ["burst_rush"],
      "score_adjustments": {"tank_single": -0.1},
      "tags_required": ["unlocked"]
    },
    "items": [...]
  }'

If constraints filter all items, the API returns 400 with a descriptive error.

Dependency Enforcement

When respect_dependencies is true (the default), items with depends_on fields are re-ordered after scoring so dependencies always appear before dependents. Within each dependency tier, items are sorted by score.

// burst_rush depends on swarm_basic
// Even if burst_rush scores higher, swarm_basic appears first
{
  "weight_profile": "activation",
  "respect_dependencies": true,
  "items": [
    {"id": "swarm_basic", "urgency": 3, "impact": 2},
    {"id": "burst_rush", "urgency": 9, "impact": 8, "depends_on": ["swarm_basic"]}
  ]
}
// Result: swarm_basic (rank 1), burst_rush (rank 2)

Set respect_dependencies: false for pure score-based ranking. Circular dependencies return 400.

Hard Gates

Binary pass/fail on a dimension. Items that fail any gate are excluded before scoring — they never enter the ranking.

// Must have at least 3 bedrooms AND price under budget
{
  "gates": [
    {"dimension": "bedroom_fit", "gate_type": "min", "threshold": 0.4},
    {"dimension": "price_fit", "gate_type": "min", "threshold": 0.1}
  ]
}
// Response includes gate_failures: items that didn't pass

Conditional Scoring

Post-scoring rules that boost, penalize, exclude, or demote items based on dimension thresholds.

{
  "conditionals": [
    {"dimension": "readiness", "operator": "lt", "threshold": 0.3,
     "action": "penalize", "action_value": 0.2, "label": "low readiness"},
    {"dimension": "roi", "operator": "gte", "threshold": 0.8,
     "action": "boost", "action_value": 0.1}
  ]
}

Actions: boost, penalize, exclude, demote, promote

Operators: lt, gt, lte, gte, eq

Weight Profiles

8 built-in profiles cover common sequencing patterns. Create custom profiles via POST /v1/weight-profiles.

Missing dimensions default to 0.5 (neutral). Weights must sum to ~1.0 (±0.01).

Either/Or Calibration

When two items score within the tie threshold (default 5%), the engine generates a calibration question instead of guessing.

// Submit calibration answer
curl -X POST https://advanseq.replit.app/v1/calibrate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_id": "q_7d3e...",
    "chosen_item_id": "task-3"
  }'

Calibration answers are stored as preference signals. Use POST /v1/resequence to re-run with updated signals.

Profile Auto-Update

When submitting a calibration answer, set auto_update_profile: trueto automatically nudge the weight profile toward the chosen item's strengths.

curl -X POST https://advanseq.replit.app/v1/calibrate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_id": "q_7d3e...",
    "chosen_item_id": "task-3",
    "auto_update_profile": true,
    "update_learning_rate": 0.1
  }'

The response includes updated weights:

{
  "accepted": true,
  "question_id": "q_7d3e...",
  "remaining_questions": 2,
  "profile_updated": true,
  "updated_weights": {
    "urgency": 0.43,
    "impact": 0.27,
    "effort": 0.19,
    "dependency_count": 0.11
  }
}

Calibration Rules

Server-side rules that control when calibration questions are generated, suppressed, or forced. Configure rules per tenant — no app code changes needed.

CRUD endpoints

Rule structure

{
  "name": "first_run_guarantee",
  "condition": "call_count == 1",
  "action": "force_question",
  "priority": 10
}

Actions

Session tracking

Pass session_id and session_metadata on POST /v1/sequence to enable session-aware rules:

{
  "weight_profile": "player_xyz",
  "session_id": "session_abc_run5",
  "session_metadata": {"deaths": 2, "run_number": 5},
  "items": [...]
}

Condition variables: call_count, last_call_age_hours, session_calibrations, session_deaths, dimension_variance, top_score_gap, plus any keys from session_metadata.

Computed Dimensions

The engine computes date-derived dimensions for you — no client-side math needed. Send raw dates, get scores.

{
  "computed_dimensions": [
    {"name": "staleness", "formula": "days_since",
     "params": {"date_field": "last_done", "normalize_days": 7}},
    {"name": "deadline_pressure", "formula": "days_until",
     "params": {"date_field": "due_date", "normalize_days": 14, "invert": true}},
    {"name": "overdue", "formula": "recurrence_overdue",
     "params": {"last_date_field": "last_completed_at", "interval_field": "recurrence_days"}}
  ],
  "items": [
    {"id": "clean-kitchen", "last_done": "2026-04-22", "recurrence_days": 3, "urgency": 0.5},
    {"id": "file-taxes", "due_date": "2026-04-30", "urgency": 0.7}
  ]
}

Built-in formulas

Use for: recurring tasks, deadline urgency, lead aging, content freshness, appointment proximity.

Explain Rankings

Get a human-readable explanation for why each item ranked where it did — with icon signatures, narratives, and dimension breakdowns.

POST /v1/explain
{
  "job_id": "abc-123",
  "format": "signature"   // "signature" | "narrative" | "breakdown"
}

Response:

{
  "explanations": [{
    "item_id": "clean-kitchen",
    "rank": 1,
    "signature": ["🔥", "⚡", "✅"],
    "signature_labels": ["Urgent", "Quick", "Ready"],
    "narrative": "Ranked #1 — high urgency (0.9) and low effort (0.2)",
    "vs_next": {
      "item_id": "file-taxes",
      "delta": 0.062,
      "why_ahead": "Higher urgency (0.90 vs 0.70) and effort"
    }
  }]
}

19 built-in icon rules: 🔥 Urgent, ⚡ Quick, 💪 High Impact, 🔗 Unblocks Others, ⏰ Time-Sensitive, 🔄 Overdue, 💰 Good Price, 📍 Great Location, and more.

Compare Items

Head-to-head comparison of any two items from a scored job. Shows which dimensions each wins on and what weight change would flip the ranking.

POST /v1/compare
{
  "job_id": "abc-123",
  "item_a": "clean-kitchen",
  "item_b": "file-taxes"
}

Response includes:

Time-Boxed Plan

"I have 90 minutes — what should I do?" Scores items then fits them into a time budget with break insertion.

POST /v1/sequence/plan
{
  "weight_profile": "activation",
  "time_budget_minutes": 90,
  "items": [
    {"id": "email", "urgency": 0.8, "effort": 0.1, "duration_minutes": 5},
    {"id": "kitchen", "urgency": 0.9, "effort": 0.3, "duration_minutes": 20},
    {"id": "taxes", "urgency": 0.7, "effort": 0.8, "duration_minutes": 45}
  ],
  "break_rules": {
    "break_after_minutes": 30,
    "break_duration_minutes": 5,
    "break_label": "Quick stretch"
  }
}

Response:

{
  "plan": [
    {"type": "task", "item_id": "email", "start_min": 0, "end_min": 5},
    {"type": "task", "item_id": "kitchen", "start_min": 5, "end_min": 25},
    {"type": "break", "label": "Quick stretch", "start_min": 25, "end_min": 30},
    {"type": "task", "item_id": "taxes", "start_min": 30, "end_min": 75}
  ],
  "time_used": 75,
  "time_remaining": 15,
  "items_excluded": []
}

Gap Analysis

When results are thin, gap analysis tells you why and what to flex.

POST /v1/analyze/gaps
{ "job_id": "abc-123" }

Returns:

Turns "no results" into "here's why and here's what to change."

Multi-Track Sequencing

N ranked lists from one request, each with different weight overrides. Same items, different priorities.

{
  "tracks": [
    {"name": "sprint", "weight_overrides": {"urgency": 0.7, "effort": 0.1}},
    {"name": "weekend", "weight_overrides": {"urgency": 0.1, "impact": 0.6}},
    {"name": "quick-wins", "filter_tags": ["easy"], "max_items": 5}
  ]
}

Use for: sprint vs tech debt, hot leads vs nurture, morning vs afternoon slots.

Diversification

Ensure top-N results span a minimum number of distinct values on a field — prevents cluster domination.

{
  "diversify": [
    {"field": "category", "top_n": 5, "min_distinct": 3}
  ]
}

Response includes diversity_reports showing actual vs target distinct values and items reordered.

Correlation Detection

Flags dimension pairs doing overlapping work — detects when you're accidentally double-counting a signal.

{ "detect_correlations": true }

// Response:
"correlations": [{
  "dim_a": "market_whitespace",
  "dim_b": "revenue_path",
  "correlation": 0.92,
  "recommendation": "merge or reduce weight"
}]

Centroid Chain (Large Sets)

For 100+ items, use centroid-chain sequencing. Groups items by a field, builds cluster centroids, applies sigma-based gating, then ranks within retained clusters.

curl -X POST https://advanseq.replit.app/v1/sequence/chain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "weight_profile": "review-decision",
    "items": [...],
    "chain": {
      "group_field": "category",
      "high_sigma": 0.15,
      "low_sigma": 0.05
    }
  }'

Resequence

Re-run a prior job with a different profile or updated items. Automatically creates a refinement link to the original job.

curl -X POST https://advanseq.replit.app/v1/resequence \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "8f2a1c3d-...",
    "weight_profile": "build-order"
  }'

Job History

Every sequence run is stored as a job. Retrieve history, inspect results, and trace refinement chains.

# List recent jobs
curl https://advanseq.replit.app/v1/jobs -H "Authorization: Bearer YOUR_API_KEY"

# Get a specific job with full detail
curl https://advanseq.replit.app/v1/jobs/8f2a1c3d-... -H "Authorization: Bearer YOUR_API_KEY"

# Trace refinement chain (job A → B → C)
curl https://advanseq.replit.app/v1/jobs/8f2a1c3d-.../chain -H "Authorization: Bearer YOUR_API_KEY"

# Export as CSV
curl "https://advanseq.replit.app/v1/jobs/8f2a1c3d-.../export?format=csv" -H "Authorization: Bearer YOUR_API_KEY"

Errors & Rate Limits

Rate limits by plan

SDKs & Tools

AdvanSeq works with any HTTP client. A Python SDK is available in the engine repo.

Python

from advanseq.sdk import AdvanSeqClient

client = AdvanSeqClient(
    api_key="ask_...",
    base_url="https://advanseq.replit.app"
)

result = client.sequence(
    weight_profile="activation",
    items=[
        {"id": "a", "urgency": 0.9, "impact": 0.7},
        {"id": "b", "urgency": 0.3, "impact": 0.9},
    ]
)

for item in result["sequence"]:
    print(f"#{item['rank']} {item['item_id']} — {item['score']:.3f}")

JavaScript / TypeScript

const res = await fetch("https://advanseq.replit.app/v1/sequence", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ask_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    weight_profile: "activation",
    items: [
      { id: "a", urgency: 0.9, impact: 0.7 },
      { id: "b", urgency: 0.3, impact: 0.9 },
    ],
  }),
});

const { sequence } = await res.json();
sequence.forEach(item =>
  console.log(`#${item.rank} ${item.item_id} — ${item.score.toFixed(3)}`)
);