Simulix

API

Workflows

Browse the calibrated workflow catalog before launching a simulation. Every workflow surfaced here has cleared the K-sample confirm gate; the listing carries the published accuracy badge, the source citations, and the original ground-truth sample size so you can audit a workflow before you POST to /v1/simulations.

Overview

Three GET endpoints — listing, taxonomy, and detail. Read-only, cursor-paginated, fail-fast on unknown filters, and gated by the workflows:read scope (seeded on every existing API key by the Day-23 migration so no key regeneration is required).

  • GET /v1/workflows — paginated catalog, optional ?category=<slug> filter.
  • GET /v1/workflows/categories — the 10 public taxonomy entries.
  • GET /v1/workflows/{workflow_id} — full workflow row including the K-sample confirm-gate breakdown (mean, min, std).

Authentication

Bearer token via the Authorization header. All three endpoints require the workflows:read scope. Existing API keys minted before the Day-23 release have the scope automatically; freshly-minted keys must request it via /docs/api-keys.

GET /v1/workflows

Cursor-paginated workflow listing. Optional ?category=<slug> filters to one of the 10 public categories. Returns at most limit rows (1..100, default 50).

Query parameters

  • category — optional category slug. Returns 400 unknown_category if the slug doesn't match any of the 10 declared categories (browse /v1/workflows/categories for valid slugs).
  • cursor — opaque cursor from the previous page's meta.next_cursor. Pass empty / null on the first request.
  • limit — page size (1..100, default 50).

Response — 200

{
  "data": [
    {
      "id": "mailchimp_email_click_rate",
      "slug": "mailchimp_email_click_rate",
      "title": "Mailchimp Email Click Rate \u2014 Cross-Industry",
      "category": "ad-performance",
      "accuracy_pct": 98.28,
      "citations": [
        "Mailchimp Email Marketing Benchmarks \u2014 average click rate across industries is about 2.62%."
      ],
      "sample_size": 1000,
      "last_calibrated_at": "2026-04-17T00:00:00Z"
    }
  ],
  "error": null,
  "meta": {
    "next_cursor": "mailchimp_email_click_rate",
    "has_more": true,
    "returned": 1
  }
}

GET /v1/workflows/categories

Returns the 10 public taxonomy entries in declaration order (the order categories appear in the customer console).

Response — 200

{
  "data": [
    {
      "slug": "ad-performance",
      "name": "Ad Performance",
      "description": "Forecast click-through, open, completion, and conversion rates ...",
      "workflow_count": 11,
      "exemplar_workflow_ids": [
        "airship_push_open_rate",
        "klaviyo_sms_click_rate",
        "mailchimp_email_click_rate"
      ]
    }
  ],
  "error": null,
  "meta": { "returned": 10 }
}

workflow_count is exactly the number of rows GET /v1/workflows?category=<slug> would return for that slug. exemplar_workflow_ids surfaces the first three workflow ids in declaration order so a UI can render a category card with sample tags without paging.

GET /v1/workflows/{workflow_id}

Single workflow with the full detail payload — adds the synthesized customer description, the aggregator id, the default agent count the workflow was calibrated at, the KPI definition, and the K-sample confirm-gate breakdown (mean / min / std) plus the primary source URL.

Response — 200

{
  "data": {
    "id": "mailchimp_email_click_rate",
    "slug": "mailchimp_email_click_rate",
    "title": "Mailchimp Email Click Rate \u2014 Cross-Industry",
    "category": "ad-performance",
    "accuracy_pct": 98.28,
    "citations": ["Mailchimp ..."],
    "sample_size": 1000,
    "last_calibrated_at": "2026-04-17T00:00:00Z",
    "description": "Mailchimp Email Marketing Benchmarks \u2014 cross-industry average click rate of 2.62% ...",
    "aggregator_id": "yes_rate",
    "agent_count_default": 100,
    "kpi_definition": "email_click_rate",
    "confirm_mean_pct": 98.28,
    "confirm_min_pct": 97.38,
    "confirm_std_pp": 0.92,
    "source_url": "https://mailchimp.com/resources/email-marketing-benchmarks/"
  },
  "error": null,
  "meta": {}
}

Workflow id vs title

The catalog returns two strings per workflow: a URL-safe slug (id / slug) and a human display name (title). Today, posting to POST /v1/simulations accepts the title as the workflow_id request field. A near-term update will accept either the slug or the title; until then, copy the title verbatim into your simulation request.

Errors

Errors follow the canonical envelope — { data: null, error: "...", meta: { ... } }.

  • 400 unknown_category — the supplied ?category= doesn't match any of the 10 declared slugs. meta.message lists the valid slugs.
  • 403 forbidden_missing_scope — the calling key doesn't carry workflows:read. meta.required_scope + meta.your_scopes identify the gap.
  • 404 workflow_not_found — the supplied workflow_id is not in the public catalog. Browse GET /v1/workflows for valid ids.
  • 422 — limit outside [1, 100].