Demo jobs

A demo job is the external resource that represents one generated company.

Internally, Fictix stores projects, org-scoped runtime routes, generated datasets, normalized entity shadows, native service records, simulation state, events, validation results, and scenario manifests. Externally, a partner should not need to stitch those pieces together. The demo_job resource is the stable wrapper around them.

Lifecycle

created -> generating -> ready
                   \-> error

Most current demo-job creates perform generation during the request and return a ready resource. Clients should still handle polling because larger or future async jobs may return before generation is complete.

Creating a job

POST /api/v1/demo-jobs
Idempotency-Key: <key>

The request has four main blocks:

{
  "company": {},
  "generation": {},
  "simulation": {},
  "scenarios": []
}

company

Describes the real or hypothetical business you want Fictix to synthesize.

Important fields:

• name
• domain
• apollo_id
• archetype
• industry
• employee_count
• annual_revenue
• customer_accounts
• company_age_months
• selected_services
• dials

generation

Controls generated data scale and quality.

Important fields:

• employees
• months_of_history
• quality_preset

Quality presets:

• clean
• realistic
• messy
• stress_test

simulation

Initializes the simulation clock and dials.

Important fields:

• seed
• start_date
• dials

scenarios

Optional planted-scenario inputs used for QA and eval flows.

Example:

{
  "scenarios": [
    {
      "id": "ghost-employee",
      "params": {
        "months": 1
      }
    }
  ]
}

Important response fields

{
  "object": "demo_job",
  "contract_version": "2026-07-17",
  "regeneration_required": false,
  "id": "8f3a2d11",
  "status": "ready",
  "links": {
    "self": "/api/v1/demo-jobs/8f3a2d11",
    "status": "/api/v1/demo-jobs/8f3a2d11/status",
    "quality": "/api/v1/demo-jobs/8f3a2d11/quality"
  },
  "company": {},
  "runtime": {},
  "dataset_summary": {},
  "quality": {},
  "credentials": {}
}

id

The partner-facing demo job identifier. Today it maps to the underlying project id. Store this as the primary key in your integration.

regeneration_required

When true, the retained company predates the current accounting contract. Regenerate it before importing its data into a workflow that requires the current contract.

links

Stable follow-up links. Prefer using links over hardcoding paths when building a generic client.

runtime

Contains lower-level identifiers:

• project_id
• slug
• publish_id

Use runtime.slug for runtime/org routes. Use publish_id for human handoff URLs.

dataset_summary

Contains record counts and entity availability. Use this to decide which loaders to run.

quality

Summarized validation status. Use the full quality endpoint for check-level details.

credentials

Includes a runtime API key for optional lower-level runtime access. Store it only when required.

Listing jobs

GET /api/v1/demo-jobs?limit=100&offset=0

The list endpoint returns visible jobs for the authenticated user/operator.

Status polling

GET /api/v1/demo-jobs/{job_id}/status

Use status polling when:

• generation may be slow
• a UI needs a progress/status state
• a worker wants to wait before loading entities

Resetting jobs

POST /api/v1/demo-jobs/{job_id}/reset

Reset requires an explicit confirmation body:

{
  "confirm": true
}

Reset clears generated runtime state and returns the job to a clean state. It is intended for iterative demo/test flows, not for ordinary data refresh. Prefer clone when you need a new independent company.

Cloning jobs

POST /api/v1/demo-jobs/{job_id}/clone

Clone creates a new project with a new runtime key and seed. Use clone when you want a similar company shape but isolated state.

Publishing jobs

POST /api/v1/demo-jobs/{job_id}/publish

Publish returns stable handoff metadata:

• publish_id
• dashboard URL
• staging URLs

Use this when a PM, solutions engineer, or customer engineer needs a stable reference to a generated company.