Response envelopes

Fictix returns generated business records, so entity-specific data can vary by company, selected services, and scenario. The partner API keeps the outer envelope stable while allowing the record payload to remain true to the generated company.

The live schema is available at:

https://api.fictix.ai/openapi.json

Use the schema for mechanical route, request, authentication, and top-level response validation. Use the catalog endpoints to discover the fields and capabilities selected for a particular company.

Contract version

Partner response envelopes include a date-based contract version:

{
  "contract_version": "2026-07-17"
}

Treat it as a string, not an integer. Store the version with any imported dataset, export, test run, or evaluation result.

Demo job

{
  "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",
    "bundle": "/api/v1/demo-jobs/8f3a2d11/bundle"
  },
  "company": {},
  "runtime": {},
  "dataset_summary": {},
  "quality": {}
}

Field	Type	Meaning
`object`	string	Stable resource type: `demo_job`.
`contract_version`	string	Partner contract version for the response.
`regeneration_required`	boolean	`true` when this company predates the current accounting contract and must be regenerated before a current-contract import.
`id`	string	Demo-job/project identifier.
`status`	string	`created`, `generating`, `ready`, `error`, or `unknown`.
`links`	object	Relative links to the job's normalized resources.
`company`	object	Generated company identity and summary.
`runtime`	object	Runtime project id, slug, and handoff metadata.
`dataset_summary`	object	Canonical record counts and materialization summary.
`quality`	object	Validation summary appropriate for fast display.

The credentials.api_key field can appear immediately after a control-plane create/clone. It is a one-time server secret; do not log or return it to a browser. Console-created companies use the Console's Company API keys flow instead.

Entity page

{
  "object": "demo_entity_page",
  "contract_version": "2026-07-17",
  "job_id": "8f3a2d11",
  "lineage": {},
  "entity": "customers",
  "count": 1200,
  "limit": 100,
  "offset": 0,
  "data": []
}

count is the total for the requested canonical entity; data contains the current page. Do not infer end-of-pagination from a short page alone—continue until offset + data.length >= count.

Catalog collection

{
  "object": "catalog_collection",
  "contract_version": "2026-07-17",
  "collection": "services",
  "count": 4,
  "items": []
}

Catalog endpoints are public and return no tenant data. They are the right source for available entities, connector capabilities, and export-pack schemas.

Error envelopes

Most errors include detail. The value may be text or a structured object:

{
  "detail": {
    "code": "project_dataset_limit_exceeded",
    "message": "Project dataset exceeds current blob storage safety budget"
  },
  "request_id": "req_example"
}

Create-time credit errors (402, and some 409, 422, and 429 responses) use a separate envelope:

{
  "error": "insufficient_credits",
  "message": "A valid credit run or sufficient credits are required."
}

Write clients that tolerate both envelope families:

type FictixDetailError = {
  detail: string | { code?: string; message?: string; [key: string]: unknown };
  request_id?: string;
};

type FictixCreditError = {
  error: string;
  message: string;
};

type FictixError = FictixDetailError | FictixCreditError;

Capture request_id, method, path, and safe job/entity identifiers when escalating a problem. Never include credentials in support logs.

CSV and JSON exports

format=json returns a demo_entity_export JSON envelope. format=csv returns text/csv and includes lineage in response headers when available. Choose CSV for file loaders and JSON for API-based transforms; do not expect the CSV endpoint to wrap rows in the JSON envelope.

Next: Entities And Exports and Errors, Limits, And Idempotency.

Runtime and native routes

Capability matrix