Call Rigor from your code

Authentication

All API requests require an API key sent via the x-api-key header. The Authorization header is not read — requests without x-api-key return 401 missing_api_key.

Keys are created at signup or via POST /api/keys. Your key identifies your organization — all workflows, billing, and data are scoped to it.

Anonymous mode (MCP only)

When connecting via MCP (Smithery, Claude Desktop, Cursor, etc.) without an API key, rigor_plan is available for evaluation against a demo org. Anonymous calls are rate-limited to 30 requests / minute and 500 requests / day per IP.

Quick start

1 · Get a key

curl -X POST https://plith.ai/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "My Org"}'

// Response — store api_key immediately, it cannot be retrieved again
{
  "org_id": "a1b2c3d4-...",
  "api_key": "plth_live_xxxxxxxxxxxx...",
  "workspace_id": "ws_...",
  "email_verified": false,
  "credits": 2500,
  "message": "Store this key securely — it will not be shown again. Verify your email to unlock 2,500 bonus credits."
}

2 · Plan a workflow (free)

curl -X POST https://plith.ai/api/rigor/plan \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_description": "Design a caching layer for our API gateway"}'

Returns a workflow_id and step sequence. No credits used.

3 · Execute

curl -X POST https://plith.ai/api/rigor/execute \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "wr_2a4b6c8d...", "delivery": {"method": "polling"}}'

4 · Get results

curl https://plith.ai/api/rigor/status/wr_2a4b6c8d... \
  -H "x-api-key: YOUR_KEY"

Returns progress during execution and the full deliverable when complete.

Credits & billing

Plith is metered in credits at 1,000 credits per USD. New organizations receive 2,500 free credits immediately on signup. Verify your email to unlock 2,500 bonus credits (5,000 total). No monthly stipend — credits never expire.

Credit packs

Purchase via POST /api/billing/checkout. Credits are deducted after each successful call; the amount deducted is reported as credits_used; your new balance as credits_remaining.

For Rigor workflows, credits accumulate server-side as steps execute. The pre-execution estimate appears in plan.cost; final usage is reported by GET /api/rigor/status as credits_used.

Rate limits

Active workflows (counting toward the concurrent limit): queued, executing, step_executing, resuming, quality_review, interactive_waiting, pending_approval, pending_human_review. When a rate limit is exceeded, the response includes retry_after (seconds) and a Retry-After HTTP header.

POST /api/rigor/plan

Classifies the task and builds a workflow plan without executing it. The plan is persisted so a subsequent /execute call can pass the workflow_id to skip re-classification.

Request body

preferences fields

Response (200)

{
  "ok": true,
  "plan": {
    "workflow_id": "wr_2a4b6c8d...",
    "classification": { "task_type": "solution_design", "value_class": "operational" },
    "sequence": [
      { "step": 1, "name": "Requirements Analysis", "estimated_credits": 80,  "priority_class": "must" },
      { "step": 2, "name": "Solution Design",        "estimated_credits": 240, "priority_class": "must" },
      { "step": 3, "name": "Assumption Verification","estimated_credits": 100, "priority_class": "should", "auto_added": true },
      { "step": 4, "name": "Review (Sonnet)",         "estimated_credits": 120, "priority_class": "must" }
    ],
    "cost": { "credits": 540, "usd": 0.54, "range": { "estimated_min": 400, "estimated_max": 680 } },
    "rigor_level": "standard",
    "warnings": [],
    "info": ["Review: Haiku + Sonnet"]
  }
}

Review step names carry the model label: "Review (Haiku)", "Review (Sonnet)", "Review (Opus)".

Errors: 401 unauthorized · 400 invalid_body · 400 missing_field · 400 invalid_task_description · 400 vague_task_description · 429 rate_limit_exceeded · 504 plan_timeout · 500 plan_error

POST /api/rigor/execute

Executes a workflow end-to-end. Pass workflow_id to re-use a stored plan, or pass task_description to classify, plan, persist, and dispatch in a single call. Cost equals the plan's cost.credits. First Rigor workflow per org is free.

Delivery modes

SSE events

Reconnect: each event carries an id: field of the form workflow_id:step_or_marker. To resume after a drop, resend the request with Last-Event-ID set to the last received id — missed events will be replayed.

GET /api/rigor/status/{workflow_id}

Returns workflow state and results. Only the owning organization can read a workflow.

Status values

pending · planned · queued · executing · step_executing · resuming · quality_review · interactive_waiting · pending_approval · pending_human_review · approved · completed · failed · cancelled · timed_out · blocked · halted

{
  "ok": true,
  "workflow": {
    "workflow_id": "wr_2a4b6c8d...",
    "status": "completed",
    "task_type": "solution_design",
    "current_step": 5,
    "total_steps": 5,
    "quality_score": 92,
    "quality_review": {
      "score": 92,
      "summary": "Strong design with clear trade-offs.",
      "path_to_100": ["Add p50/p95/p99 latency targets per cache tier."]
    },
    "deliverable": { "title": "...", "sections": [{ "heading": "...", "content": "..." }] },
    "credits_used": 530,
    "error": null
  }
}

POST /api/rigor/approve

{
  "workflow_id": "wr_2a4b6c8d...",
  "decision": "approved",
  "notes": "OK to proceed",
  "agent_id": "my-review-bot"
}

Decision endpoint for workflows paused at pending_approval. On approval, the workflow automatically resumes. On rejection, the workflow is marked failed. Errors: 404 not_found · 409 invalid_status · 500 approve_failed

POST /api/rigor/resume

{
  "workflow_id": "wr_2a4b6c8d...",
  "revision_guidance": "Focus the rewrite on enterprise buyers; ignore SMB."
}

Resumes a workflow from the last completed step. Permitted source statuses: executing, failed, approved, blocked, timed_out, pending_approval. Uses an optimistic lock — concurrent resume calls return resume_conflict.

POST /api/rigor/step

{
  "workflow_id": "wr_2a4b6c8d...",
  "action": "next",
  "feedback": "Focus on security implications."
}

Drives a workflow created with mode: "interactive". action accepts "next" | "skip" | "abort". Sessions expire after 30 minutes of inactivity. Errors: 409 invalid_status · 410 session_expired · 409 concurrent_step

GET /api/rigor/workflows

Lists workflows for the authenticated org with filtering and cursor-based pagination. Also returns a real-time concurrent-usage summary against your plan's concurrent workflow limit.

POST /api/rigor/workflows/actions

{
  "action": "cancel",
  "workflow_ids": ["wr_aaa...", "wr_bbb..."],
  "confirm": false,
  "force": false
}

Bulk workflow action endpoint. Currently supports action: "cancel". Two-phase: confirm: false (default) shows a preview, confirm: true executes. Max 20 workflow IDs per call.

GET /api/rigor/lineage/{workflowId}

Walks the prior_workflow_id chain backward and returns the full lineage, ordered oldest-first. Capped at 10 hops. Errors: 404 not_found · 422 chain_depth_exceeded

GET /api/rigor/templates

{
  "templates": [{
    "id": "uuid",
    "task_type": "solution_design",
    "template_name": "Solution Design",
    "template_prompt": "...",
    "placeholder_fields": ["system_name", "constraints"],
    "description": "Architecture and design document for a technical system.",
    "display_order": 1,
    "version": 1,
    "category": "Engineering"
  }]
}

Returns deliverable templates — 43 types across 8 categories. No auth required. Query: ?task_type= and/or ?category=.

POST /api/rigor/enhance

{ "task_description": "Design a caching layer", "tier": "llm" }

Scores and optionally enhances a task description. tier: "deterministic" (default) is free, rule-based, no auth. tier: "llm" uses an LLM for richer suggestions — 270 credits, requires x-api-key. Response includes score (0–100), suggestions[], and (for llm tier) enhanced_prompt — a rewritten task. Errors: 400 input_too_long (10,000 char max) · 500 enhance_error

POST /api/rigor/connections

Registers a new MCP server connection. Server URL is validated for SSRF safety at registration time. Credentials are encrypted at rest immediately and never returned. Returns 201 with connection.status: "pending". Call /test to promote to active.

GET /api/rigor/connections

Returns all connections registered for your organization. Credentials are never included. Status values: pending, active, error, revoked. capabilities is null until a connection test completes.

PATCH /api/rigor/connections/{id}

Updates a registered connection. All fields optional.

POST /api/rigor/connections/{id}/test

Tests connectivity. Performs DNS-level SSRF check. On success, status → active, last_tested_at recorded. On SSRF failure, status → error and the response is 400.

DELETE /api/rigor/connections/{id}

Soft delete. Record retained for audit, status set to revoked, credentials cleared. Revoked connections cannot be used in workflow execution.

Connection security

Limits: max 10 connections per org · duplicate server_url rejected with 409 · HTTPS only.

MCP tools

Connect to Plith via MCP at https://plith.ai/api/mcp/rigor. Compatible with Claude Desktop, Cursor, Windsurf, Smithery, and any MCP-compatible client. Authenticate via the x-api-key header, or use anonymous mode (rate-limited: 30 req/min, 500 req/day per IP) for evaluation.

Discoverable tools

Hidden tools

Callable but do not appear in tools/list:

Plan-then-execute (recommended)

Plan first to see the step sequence and cost estimate. Execute only when satisfied.

# Step 1: Plan (free)
POST /api/rigor/plan
  { "task_description": "...", "preferences": { "rigor_level": "standard" } }
  → { plan: { workflow_id: "wr_...", sequence: [...], cost: { credits: 540 } } }

# Step 2: Execute with polling delivery
POST /api/rigor/execute
  { "workflow_id": "wr_...", "delivery": { "method": "polling" } }
  → { workflow_id: "wr_...", status: "queued", poll_url: "/api/rigor/status/wr_..." }

# Step 3: Poll until "completed"
GET /api/rigor/status/wr_...
  → { workflow: { status: "completed", deliverable: { ... } } }

Webhook delivery

Receive results pushed to your endpoint instead of polling. Store webhook_secret and verify incoming payloads via HMAC-SHA256.

POST /api/rigor/execute
  {
    "workflow_id": "wr_...",
    "delivery": {
      "method": "webhook",
      "webhook_url": "https://your-server.example.com/rigor-webhook"
    }
  }
  → { webhook_url: "...", webhook_status: "registered", webhook_secret: "..." }

Approval gate

Request a human decision before final steps execute.

# Plan with approval gate
POST /api/rigor/plan
  { "task_description": "...", "preferences": { "require_approval": true } }

# Execute — workflow will pause at pending_approval
POST /api/rigor/execute
  { "workflow_id": "wr_...", "delivery": { "method": "polling" } }

# Poll until status === "pending_approval", then approve
POST /api/rigor/approve
  { "workflow_id": "wr_...", "decision": "approved", "notes": "Looks good" }
  # workflow automatically resumes after approval

Interactive mode

Drive execution one step at a time. Sessions expire after 30 minutes of inactivity.

POST /api/rigor/execute
  { "task_description": "...", "mode": "interactive" }
  → { status: "interactive_waiting", sequence: [...] }

POST /api/rigor/step
  { "workflow_id": "wr_...", "action": "next" }
  → { status: "step_executing", poll_url: "..." }

Workflow chaining

Inherit context from a completed workflow into a new one. Chain depth limit: 10 links.

POST /api/rigor/execute
  {
    "task_description": "Implement the solution from the prior design",
    "prior_workflow_id": "wr_parent...",
    "context_fields": ["deliverable", "quality_review"]
  }

Worked example

A complete plan → execute → poll cycle for a Solution Design.

curl -X POST https://plith.ai/api/rigor/plan \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_description": "Design a caching layer for our API"}'

# → plan.cost.credits = 560 · estimated cost shown before committing

curl -X POST https://plith.ai/api/rigor/execute \
  -H "x-api-key: YOUR_KEY" \
  -d '{"workflow_id": "wr_...", "delivery": {"method": "polling"}}'

# → status: queued · poll_url returned

curl https://plith.ai/api/rigor/status/wr_... \
  -H "x-api-key: YOUR_KEY"

# → status: completed · quality_score: 92 · credits_used: 545

Error reference

All endpoints return errors in this envelope:

{
  "error": {
    "code": "missing_field",
    "message": "workflow_id is required.",
    "request_id": "req_abc123def456...",
    "fix": "POST /api/rigor/plan with your task_description",
    "docs": "https://plith.ai/docs/errors#missing_field",
    "details": { "field": "workflow_id" }
  }
}

fix, docs, and details are included only when available. request_id is always present.

Auth

Validation

Rate limiting

Workflow state

Chaining & connections

Response conventions

Every successful response includes:

Rigor workflow endpoints (/plan, /execute, /status, /approve, /resume, /step) use product-specific response shapes and do not include credits_used / credits_remaining at the top level. Credit usage for workflows is reported via the status endpoint as workflow.credits_used.