HTTP reference

Every endpoint with its parameters, schemas and a request you can copy. Generated from the supported contract; nothing on this page sends a request.

Base path
/api/customer/v1
Authentication
Authorization: Bearer YOUR_API_KEY
Contract
Download OpenAPI JSON

Uploads

Create Upload

POST/datasets/uploads

Requires datasets:write

Parameters

No path, query or header parameters.

Request body

application/json, required

conversation_id union · optional
Alternative 1

string

maxLength: 128

Alternative 2

null

dataset_id union · optional
Alternative 1

string

maxLength: 128

Alternative 2

null

filename string · required

string

maxLength: 255

minLength: 1

purpose string · optional

string

Allowed: ["dataset","questionnaire"]

default: "dataset"

size_bytes integer · required

integer

tool_key union · optional
Alternative 1

string

maxLength: 128

Alternative 2

null

Additional fields: not allowed

Responses

201Successful Response

application/json

expires_in integer · required

integer

headers object · required

object

Additional fields: allowed

method string · required

string

Value: "PUT"

upload_id string · required

string

upload_url string · required

string

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X POST "$CM_API_BASE/datasets/uploads" \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
Request body shape
{
  "filename": "string",
  "size_bytes": 0
}
Response 201 shape
{
  "expires_in": 0,
  "headers": {},
  "method": "PUT",
  "upload_id": "string",
  "upload_url": "string"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Cancel Upload

DELETE/datasets/uploads/{upload_id}

Requires datasets:write

Parameters

upload_id path, required

string

Request body

No request body.

Responses

204Successful Response

No response body.

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X DELETE "$CM_API_BASE/datasets/uploads/{upload_id}" \
  -H "Authorization: Bearer $CM_API_KEY"

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Complete Upload

POST/datasets/uploads/{upload_id}/complete

Requires datasets:write

Parameters

upload_id path, required

string

Request body

No request body.

Responses

200Completed dataset upload, or queued questionnaire processing when purpose is questionnaire.

application/json

Alternative 1

Data upload response model.

dataset_id string · required

Dataset identifier

string

message string · required

Status message

string

metadata object · required

Dataset metadata.

created_at string · required

Creation timestamp

string

format: "date-time"

dataset_id string · required

Dataset identifier

string

description union · optional

Dataset description

Alternative 1

string

Alternative 2

null

file_type string · required

File type

string

filename string · required

Original filename

string

metadata object · optional

Additional metadata

object

Additional fields: allowed

total_columns integer · required

Total number of columns

integer

total_rows integer · required

Total number of rows

integer

success boolean · required

Upload success status

boolean

upload_time string · required

Upload timestamp

string

format: "date-time"

variable_catalog array · required

Variable catalog

array

Array item schema

Variable information.

date_range union · optional

Min/max for a date variable, bounding the filter picker

Alternative 1

Earliest and latest value of a date variable, ISO-8601.

max string · required

Latest value, ISO-8601

string

min string · required

Earliest value, ISO-8601

string

Alternative 2

null

description union · optional

Variable description

Alternative 1

string

Alternative 2

null

missing_count union · optional

Number of missing values

Alternative 1

integer

Alternative 2

null

name string · required

Variable name

string

type string · required

Ported from `crowdmines_db.enums.VariableType`, values unchanged.

string

Allowed: ["categorical","numerical","ordinal","text","date","boolean"]

unique_values union · optional

Number of unique values

Alternative 1

integer

Alternative 2

null

Alternative 2
success boolean · required

boolean

dataset_id string · required

string

task_id string · required

string

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X POST "$CM_API_BASE/datasets/uploads/{upload_id}/complete" \
  -H "Authorization: Bearer $CM_API_KEY"
Response 200 shape
{
  "dataset_id": "string",
  "message": "string",
  "metadata": {
    "created_at": "2026-01-01T00:00:00Z",
    "dataset_id": "string",
    "file_type": "string",
    "filename": "string",
    "total_columns": 0,
    "total_rows": 0
  },
  "success": true,
  "upload_time": "2026-01-01T00:00:00Z",
  "variable_catalog": [
    {
      "name": "string",
      "type": "categorical"
    }
  ]
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Datasets

Read Limits

GET/datasets/limits

Requires datasets:read

Parameters

No path, query or header parameters.

Request body

No request body.

Responses

200Successful Response

application/json

Both caps: core's proxy reads the data file's, the MCP upload card both.

max_bytes integer · required

integer

questionnaire_max_bytes integer · required

integer

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X GET "$CM_API_BASE/datasets/limits" \
  -H "Authorization: Bearer $CM_API_KEY"
Response 200 shape
{
  "max_bytes": 0,
  "questionnaire_max_bytes": 0
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Get Dataset

GET/datasets/{dataset_id}

Requires datasets:read

Parameters

dataset_id path, required

string

Request body

No request body.

Responses

200Successful Response

application/json

The whole row, for service-to-service use. SurveyGuard and the analysis tools resolve a `dataset_id` to a `storage_key` through this route rather than reaching into the schema — the ownership check happens once, here, and the tool never sees a JWT.

column_labels object · optional

object

Additional fields: allowed

column_names array · optional

array

Array item schema

string

column_types object · optional

object

Additional fields: allowed

column_unique_values object · optional

object

Additional fields: allowed

conversation_id union · optional
Alternative 1

string

Alternative 2

null

dataset_id string · required

string

file_type string · required

string

filename string · required

string

is_processed boolean · optional

boolean

default: false

n_rows union · optional
Alternative 1

integer

Alternative 2

null

n_vars union · optional
Alternative 1

integer

Alternative 2

null

org_id string · required

string

original_filename string · required

string

processing_error union · optional
Alternative 1

string

Alternative 2

null

questionnaire_sha256 union · optional
Alternative 1

string

Alternative 2

null

questionnaire_skipped boolean · optional

boolean

default: false

questionnaire_storage_key union · optional
Alternative 1

string

Alternative 2

null

size_bytes integer · required

integer

storage_key union · optional
Alternative 1

string

Alternative 2

null

uploaded_at string · required

string

format: "date-time"

user_id union · optional
Alternative 1

string

Alternative 2

null

value_labels object · optional

object

Additional fields: allowed

variable_catalog array · optional

array

Array item schema

object

Additional fields: allowed

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X GET "$CM_API_BASE/datasets/{dataset_id}" \
  -H "Authorization: Bearer $CM_API_KEY"
Response 200 shape
{
  "dataset_id": "string",
  "file_type": "string",
  "filename": "string",
  "org_id": "string",
  "original_filename": "string",
  "size_bytes": 0,
  "uploaded_at": "2026-01-01T00:00:00Z"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Projects and checks

Create a new project for a dataset, owned by the caller

POST/surveyguard/projects

Requires surveyguard:write

Parameters

No path, query or header parameters.

Request body

application/json, required

dataset_id string · required

Id of a dataset in the datasets service.

string

name union · optional

Display name; defaults to the dataset's filename.

Alternative 1

string

Alternative 2

null

Responses

200Successful Response

application/json

Full project record: the latest run's configuration and the ref to its results. Never the results themselves.

active_runs array · required

array

Array item schema

Persisted job status; contains no inputs or respondent evidence.

run_id string · required

string

started_at string · required

string

status string · required

string

Allowed: ["QUEUED","RUNNING","COMPLETED","FAILED"]

affected_respondent_count union · required
Alternative 1

integer

Alternative 2

null

approved_flags array · required

Reviewer-approved (confirmed real) flags — same key shape as dismissed_flags. Purely a review marker: scoring is unaffected. Reset on every new run.

array

Array item schema

string

config union · required
Alternative 1

The run configuration the user chose for this project.

m5_checks array · required

DEPRECATED — use module_checks['M5']. Kept so saved projects load.

array

Array item schema

string

m6v2_kinds array · required

M6v2 rule kinds (cont_v2_*); empty = the default set.

array

Array item schema

string

mex_combos array · required

Forbidden answer combinations (M-EX).

array

Array item schema
action string · required

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

conditions array · required

array

Array item schema
value union · required

Convenience single answer (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · required

Allowed answer code(s); respondent matches if their answer is any of these.

array

Array item schema

any JSON value

variable string · required

A closed question's column.

string

id union · required

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · required

Human description of this forbidden combination.

string

default: ""

severity union · required

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

module_checks object · required

Per-module check selection, e.g. {'M1': ['TIMING_001']}. A module absent from the map runs all of its checks. Supersedes m5_checks.

object

Additional fields: allowed

modules array · required

Detection guards to run; empty = all available.

array

Array item schema

string

policy_overrides union · required

Partial M11 PolicyConfig overrides for this project, e.g. {'clean_readiness_min': 70}. Persisted, and re-applied on every triage re-score so dismissing a flag cannot silently revert to the default. Two keys are set by the product's own scoring board and are the only ones the UI writes: 'scoring_mode' ('default' | 'custom') and 'check_verdicts' (check_id -> CLEAN | REVIEW | EXCLUDE, read only in custom mode). Everything else here stays an API-level calibration knob.

Alternative 1

object

Additional fields: allowed

Alternative 2

null

removal_rules array · required

Analyst-defined single-question removal rules (the USER module), saved with the project and re-applied on every run. Each matching respondent gets a USER_<rule> flag: EXCLUDE rules at severity 5, REVIEW rules at severity 3. Empty = the module does not run.

array

Array item schema
action string · required

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

id union · required

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · required

Human description shown on the flag.

string

default: ""

operator string · required

One of: equals, eq, not_equals, ne, in, not_in, is_missing, is_null, is_answered, not_missing, gt, gte, lt, lte.

string

default: "equals"

severity union · required

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

value union · required

Convenience single value (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · required

Comparison value(s).

array

Array item schema

any JSON value

variable string · required

Column the condition tests.

string

survey_country union · required

ISO-2 code of the market this survey was fielded in, e.g. 'US'. Drives the out-of-market checks; inferred from the sample when omitted.

Alternative 1

string

Alternative 2

null

use_llm boolean · required

Enable the model-backed layers.

boolean

default: false

Alternative 2

null

created_at string · required

string

dataset_id string · required

Id of a dataset in the global datasets service. SurveyGuard has no upload path of its own; ownership was validated there.

string

dismissed_combos array · required

Reviewer-dismissed M6v2 rules (rule_ids) — hides every flag the rule produced. Reset on every new run.

array

Array item schema

string

dismissed_flags array · required

Reviewer-dismissed flags in the latest run's results (keys: '<respondent_id>|<check_id>' or, for stored pre-grouping runs, '<respondent_id>|<check_id>|<index>'). Reset on every new run.

array

Array item schema

string

flag_occurrence_count union · required
Alternative 1

integer

Alternative 2

null

has_results boolean · required

boolean

default: false

id string · required

string

latest_export_status union · required
Alternative 1

string

Alternative 2

null

latest_run_id union · required
Alternative 1

string

Alternative 2

null

latest_run_status union · required
Alternative 1

string

Allowed: ["QUEUED","RUNNING","COMPLETED","FAILED"]

Alternative 2

null

n_respondents union · required
Alternative 1

integer

Alternative 2

null

name string · required

string

org_id string · required

string

owner_id string · required

Core user id of the creator. A project is visible only to its owner, within its org — a miss is a 404, never a 403.

string

result_ref union · required

Object-storage key of the latest run's result.json (sg/{run_id}/result.json, in the artifacts bucket). Fetch it through GET /api/pipeline2/runs/{run_id}/result — evidence never travels in this response and never lands in Postgres.

Alternative 1

string

Alternative 2

null

result_run_id union · required
Alternative 1

string

Alternative 2

null

review_revision integer · required

integer

default: 0

tier_counts object · required

object

Additional fields: allowed

total_flags union · required
Alternative 1

integer

Alternative 2

null

updated_at string · required

string

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X POST "$CM_API_BASE/surveyguard/projects" \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
Request body shape
{
  "dataset_id": "string"
}
Response 200 shape
{
  "active_runs": [
    {
      "run_id": "string",
      "started_at": "string",
      "status": "QUEUED"
    }
  ],
  "affected_respondent_count": 0,
  "approved_flags": [
    "string"
  ],
  "config": {
    "m5_checks": [
      "string"
    ],
    "m6v2_kinds": [
      "string"
    ],
    "mex_combos": [
      {
        "action": "string",
        "conditions": [
          null
        ],
        "id": null,
        "label": "string",
        "severity": null
      }
    ],
    "module_checks": {},
    "modules": [
      "string"
    ],
    "policy_overrides": {},
    "removal_rules": [
      {
        "action": "string",
        "id": null,
        "label": "string",
        "operator": "string",
        "severity": null,
        "value": null,
        "values": [
          null
        ],
        "variable": "string"
      }
    ],
    "survey_country": "string",
    "use_llm": true
  },
  "created_at": "string",
  "dataset_id": "string",
  "dismissed_combos": [
    "string"
  ],
  "dismissed_flags": [
    "string"
  ],
  "flag_occurrence_count": 0,
  "has_results": true,
  "id": "string",
  "latest_export_status": "string",
  "latest_run_id": "string",
  "latest_run_status": "QUEUED",
  "n_respondents": 0,
  "name": "string",
  "org_id": "string",
  "owner_id": "string",
  "result_ref": "string",
  "result_run_id": "string",
  "review_revision": 0,
  "tier_counts": {},
  "total_flags": 0,
  "updated_at": "string"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Configuration

GET/surveyguard/projects/{project_id}/configuration

Requires surveyguard:read

Parameters

project_id path, required

string

Request body

No request body.

Responses

200Successful Response

application/json

catalogue object · required

object

Additional fields: allowed

catalogue_version string · required

string

draft object · required
catalogue_version string · required

string

maxLength: 100

guards object · required

object

Additional fields: allowed

mex object · required
enabled boolean · required

boolean

default: false

items array · required

array

maxItems: 200

Array item schema
action string · required

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

conditions array · required

array

Array item schema
value union · required

Convenience single answer (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · required

Allowed answer code(s); respondent matches if their answer is any of these.

array

Array item schema

any JSON value

variable string · required

A closed question's column.

string

id union · required

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · required

Human description of this forbidden combination.

string

default: ""

severity union · required

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

Additional fields: not allowed

policy_overrides object · required

object

Additional fields: allowed

removal_rules array · required

array

maxItems: 200

Array item schema
action string · required

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

id union · required

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · required

Human description shown on the flag.

string

default: ""

operator string · required

One of: equals, eq, not_equals, ne, in, not_in, is_missing, is_null, is_answered, not_missing, gt, gte, lt, lte.

string

default: "equals"

severity union · required

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

value union · required

Convenience single value (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · required

Comparison value(s).

array

Array item schema

any JSON value

variable string · required

Column the condition tests.

string

schema_version integer · required

integer

Value: 1

default: 1

scoring object · required
check_verdicts object · required

object

Additional fields: allowed

mode string · required

string

Allowed: ["default","custom"]

default: "default"

Additional fields: not allowed

survey_country union · required
Alternative 1

string

maxLength: 8

Alternative 2

null

use_llm boolean · required

boolean

default: true

Additional fields: not allowed

issues array · required

array

Array item schema
message string · required

string

path string · required

string

Additional fields: not allowed

result_run_id union · required
Alternative 1

string

Alternative 2

null

result_setup_revision union · required
Alternative 1

integer

Alternative 2

null

revision integer · required

integer

updated_at union · required
Alternative 1

string

Alternative 2

null

Additional fields: not allowed

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/projects/{project_id}/configuration" \
  -H "Authorization: Bearer $CM_API_KEY"
Response 200 shape
{
  "catalogue": {},
  "catalogue_version": "string",
  "draft": {
    "catalogue_version": "string",
    "guards": {},
    "mex": {
      "enabled": true,
      "items": [
        {
          "action": "string",
          "conditions": [
            null
          ],
          "id": null,
          "label": "string",
          "severity": null
        }
      ]
    },
    "policy_overrides": {},
    "removal_rules": [
      {
        "action": "string",
        "id": "string",
        "label": "string",
        "operator": "string",
        "severity": 0,
        "value": "string",
        "values": [
          "string"
        ],
        "variable": "string"
      }
    ],
    "schema_version": 1,
    "scoring": {
      "check_verdicts": {},
      "mode": "default"
    },
    "survey_country": "string",
    "use_llm": true
  },
  "issues": [
    {
      "message": "string",
      "path": "string"
    }
  ],
  "result_run_id": "string",
  "result_setup_revision": 0,
  "revision": 0,
  "updated_at": "string"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Save Configuration

PUT/surveyguard/projects/{project_id}/configuration

Requires surveyguard:write

Parameters

project_id path, required

string

Request body

application/json, required

draft object · required
catalogue_version string · required

string

maxLength: 100

guards object · required

object

Additional fields: allowed

mex object · optional
enabled boolean · optional

boolean

default: false

items array · optional

array

maxItems: 200

Array item schema
action string · optional

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

conditions array · optional

array

Array item schema
value union · optional

Convenience single answer (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · optional

Allowed answer code(s); respondent matches if their answer is any of these.

array

Array item schema

any JSON value

variable string · required

A closed question's column.

string

id union · optional

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · optional

Human description of this forbidden combination.

string

default: ""

severity union · optional

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

Additional fields: not allowed

policy_overrides object · optional

object

Additional fields: allowed

removal_rules array · optional

array

maxItems: 200

Array item schema
action string · optional

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

id union · optional

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · optional

Human description shown on the flag.

string

default: ""

operator string · optional

One of: equals, eq, not_equals, ne, in, not_in, is_missing, is_null, is_answered, not_missing, gt, gte, lt, lte.

string

default: "equals"

severity union · optional

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

value union · optional

Convenience single value (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · optional

Comparison value(s).

array

Array item schema

any JSON value

variable string · required

Column the condition tests.

string

schema_version integer · optional

integer

Value: 1

default: 1

scoring object · optional
check_verdicts object · optional

object

Additional fields: allowed

mode string · optional

string

Allowed: ["default","custom"]

default: "default"

Additional fields: not allowed

survey_country union · optional
Alternative 1

string

maxLength: 8

Alternative 2

null

use_llm boolean · optional

boolean

default: true

Additional fields: not allowed

expected_revision integer · required

integer

minimum: 0

Additional fields: not allowed

Responses

200Successful Response

application/json

catalogue object · required

object

Additional fields: allowed

catalogue_version string · required

string

draft object · required
catalogue_version string · required

string

maxLength: 100

guards object · required

object

Additional fields: allowed

mex object · required
enabled boolean · required

boolean

default: false

items array · required

array

maxItems: 200

Array item schema
action string · required

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

conditions array · required

array

Array item schema
value union · required

Convenience single answer (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · required

Allowed answer code(s); respondent matches if their answer is any of these.

array

Array item schema

any JSON value

variable string · required

A closed question's column.

string

id union · required

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · required

Human description of this forbidden combination.

string

default: ""

severity union · required

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

Additional fields: not allowed

policy_overrides object · required

object

Additional fields: allowed

removal_rules array · required

array

maxItems: 200

Array item schema
action string · required

EXCLUDE or REVIEW; anything else fails closed to REVIEW.

string

default: "REVIEW"

id union · required

Stable id; auto-generated when omitted.

Alternative 1

string

Alternative 2

null

label string · required

Human description shown on the flag.

string

default: ""

operator string · required

One of: equals, eq, not_equals, ne, in, not_in, is_missing, is_null, is_answered, not_missing, gt, gte, lt, lte.

string

default: "equals"

severity union · required

1–5; defaults to 5 for EXCLUDE, 3 for REVIEW.

Alternative 1

integer

Alternative 2

null

value union · required

Convenience single value (folded into values).

Alternative 1

any JSON value

Alternative 2

null

values array · required

Comparison value(s).

array

Array item schema

any JSON value

variable string · required

Column the condition tests.

string

schema_version integer · required

integer

Value: 1

default: 1

scoring object · required
check_verdicts object · required

object

Additional fields: allowed

mode string · required

string

Allowed: ["default","custom"]

default: "default"

Additional fields: not allowed

survey_country union · required
Alternative 1

string

maxLength: 8

Alternative 2

null

use_llm boolean · required

boolean

default: true

Additional fields: not allowed

issues array · required

array

Array item schema
message string · required

string

path string · required

string

Additional fields: not allowed

result_run_id union · required
Alternative 1

string

Alternative 2

null

result_setup_revision union · required
Alternative 1

integer

Alternative 2

null

revision integer · required

integer

updated_at union · required
Alternative 1

string

Alternative 2

null

Additional fields: not allowed

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X PUT "$CM_API_BASE/surveyguard/projects/{project_id}/configuration" \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
Request body shape
{
  "draft": {
    "catalogue_version": "string",
    "guards": {}
  },
  "expected_revision": 0
}
Response 200 shape
{
  "catalogue": {},
  "catalogue_version": "string",
  "draft": {
    "catalogue_version": "string",
    "guards": {},
    "mex": {
      "enabled": true,
      "items": [
        {
          "action": "string",
          "conditions": [
            null
          ],
          "id": null,
          "label": "string",
          "severity": null
        }
      ]
    },
    "policy_overrides": {},
    "removal_rules": [
      {
        "action": "string",
        "id": "string",
        "label": "string",
        "operator": "string",
        "severity": 0,
        "value": "string",
        "values": [
          "string"
        ],
        "variable": "string"
      }
    ],
    "schema_version": 1,
    "scoring": {
      "check_verdicts": {},
      "mode": "default"
    },
    "survey_country": "string",
    "use_llm": true
  },
  "issues": [
    {
      "message": "string",
      "path": "string"
    }
  ],
  "result_run_id": "string",
  "result_setup_revision": 0,
  "revision": 0,
  "updated_at": "string"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Batches

Create Batch

POST/surveyguard/batches

Requires surveyguard:write

This endpoint starts billable work. Keep the exact body and Idempotency-Key when retrying. A 202 response is not a completed result.

Parameters

idempotency-key header, required

string

maxLength: 100

minLength: 8

pattern: "^[A-Za-z0-9_-]+$"

Request body

application/json, required

items array · required

array

maxItems: 10

minItems: 1

Array item schema
configuration_revision integer · required

integer

minimum: 0

item_id string · required

string

maxLength: 80

minLength: 1

pattern: "^[A-Za-z0-9_-]+$"

project_id string · required

string

maxLength: 128

minLength: 1

pattern: "^[A-Za-z0-9_-]+$"

Additional fields: not allowed

Additional fields: not allowed

Responses

202Successful Response

application/json

batch_id string · required

string

items array · required

array

Array item schema
configuration_revision integer · required

integer

error_code union · required
Alternative 1

integer

Alternative 2

null

item_id string · required

string

project_id string · required

string

run_id union · required
Alternative 1

string

Alternative 2

null

status string · required

string

Allowed: ["pending","queued","running","succeeded","failed"]

Additional fields: not allowed

status string · required

string

Allowed: ["pending","running","succeeded","partial_failure","failed"]

Additional fields: not allowed

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X POST "$CM_API_BASE/surveyguard/batches" \
  -H "Authorization: Bearer $CM_API_KEY" \
  -H "Idempotency-Key: $CM_BATCH_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data-binary @request.json
Request body shape
{
  "items": [
    {
      "configuration_revision": 0,
      "item_id": "string",
      "project_id": "string"
    }
  ]
}
Response 202 shape
{
  "batch_id": "string",
  "items": [
    {
      "configuration_revision": 0,
      "error_code": 0,
      "item_id": "string",
      "project_id": "string",
      "run_id": "string",
      "status": "pending"
    }
  ],
  "status": "pending"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Get Batch

GET/surveyguard/batches/{batch_id}

Requires surveyguard:read

Parameters

batch_id path, required

string

Request body

No request body.

Responses

200Successful Response

application/json

batch_id string · required

string

items array · required

array

Array item schema
configuration_revision integer · required

integer

error_code union · required
Alternative 1

integer

Alternative 2

null

item_id string · required

string

project_id string · required

string

run_id union · required
Alternative 1

string

Alternative 2

null

status string · required

string

Allowed: ["pending","queued","running","succeeded","failed"]

Additional fields: not allowed

status string · required

string

Allowed: ["pending","running","succeeded","partial_failure","failed"]

Additional fields: not allowed

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/batches/{batch_id}" \
  -H "Authorization: Bearer $CM_API_KEY"
Response 200 shape
{
  "batch_id": "string",
  "items": [
    {
      "configuration_revision": 0,
      "error_code": 0,
      "item_id": "string",
      "project_id": "string",
      "run_id": "string",
      "status": "pending"
    }
  ],
  "status": "pending"
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.

Runs and results

Poll a run: status, per-stage progress, tier counts and the result ref

GET/surveyguard/runs/{run_id}

Requires surveyguard:read

Parameters

run_id path, required

string

Request body

No request body.

Responses

200Successful Response

application/json

A run's status, read from its rows. **Not from Celery task state**, which expires after 24 h (data.md § Retention) — the row is the authority.

check_count union · required
Alternative 1

integer

Alternative 2

null

dataset_id union · required
Alternative 1

string

Alternative 2

null

elapsed_s number · required

number

default: 0

error union · required
Alternative 1

string

Alternative 2

null

finished_at union · required
Alternative 1

string

Alternative 2

null

partial_ref union · required

Object-storage key for the latest committed interim revision.

Alternative 1

string

Alternative 2

null

partial_revision integer · required

integer

default: 0

project_id union · required
Alternative 1

string

Alternative 2

null

respondent_count union · required
Alternative 1

integer

Alternative 2

null

result_ref union · required

Object-storage key of the full result (evidence included). Fetch it via GET /api/pipeline2/runs/{run_id}/result; it is never inlined here and never stored in Postgres.

Alternative 1

string

Alternative 2

null

run_id string · required

string

stages array · required

array

Array item schema

One row of `surveyguard.sg_stages`, as the progress strip reads it. ``checks_run`` and ``checks_skipped`` are check IDS. They are never flags and never evidence — the column they come from carries the same rule. **A `skipped` stage may still carry counts.** An LLM quota refusal takes out a module's model-backed checks and leaves its deterministic ones, which ran and whose flags are in the run's total — so the row reports them rather than contradicting its own run. Tell the two apart by `checks_run`: * `status="skipped"` with a non-empty `checks_run` — **partially skipped**; the named checks produced a verdict, `checks_skipped` did not, and their result is unknown rather than clean. * `status="skipped"` with `checks_run == []` — **skipped entirely**: not selected, or nothing configured for it.

check_progress object · required

object

Additional fields: allowed

checks_run array · required

array

Array item schema

string

checks_skipped array · required

array

Array item schema

string

duration_ms union · required
Alternative 1

integer

Alternative 2

null

flag_count integer · required

integer

default: 0

id string · required

string

label string · required

string

note union · required
Alternative 1

string

Alternative 2

null

partial_ref union · required

Object-storage key of the interim result published when this stage finished. Fetch it via GET /api/pipeline2/runs/{run_id}/partial.

Alternative 1

string

Alternative 2

null

progress_pct number · required

number

default: 0

status string · required

pending | running | done | skipped | failed

string

default: "pending"

started_at union · required
Alternative 1

string

Alternative 2

null

status string · required

QUEUED | RUNNING | COMPLETED | FAILED

string

default: "QUEUED"

tier_counts object · required

object

Additional fields: allowed

400Invalid request or unsupported file format.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

401Missing, invalid, expired or revoked API key.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

403Insufficient scope, membership or account eligibility.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

404Resource missing or inaccessible to this caller.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

409Conflict: reconcile configuration revision or idempotency payload; do not blindly retry.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

410Upload expired, cancelled or no longer available.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

413Request or file exceeds its limit.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

415Use application/json for nonempty request bodies.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

422Validation Error

application/json

detail array · optional

array

Array item schema
ctx object · optional

object

input schema · optional

any JSON value

loc array · required

array

Array item schema
Alternative 1

string

Alternative 2

integer

msg string · required

string

type string · required

string

429Organization request budget exceeded. Honor Retry-After.

Header Retry-After: Delay in seconds, or an HTTP date.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

503Temporary service failure; retry only safe operations with bounded backoff.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

defaultOther upstream error; inspect the response before retrying.

application/json

Gateway errors use a string detail. Upstream validation/quota errors may include structured detail and additional fields.

detail union · optional
Alternative 1

string

Alternative 2

object

Additional fields: allowed

Alternative 3

array

Array item schema

object

Additional fields: allowed

Additional fields: allowed

Request
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/runs/{run_id}" \
  -H "Authorization: Bearer $CM_API_KEY"
Response 200 shape
{
  "check_count": 0,
  "dataset_id": "string",
  "elapsed_s": 0,
  "error": "string",
  "finished_at": "string",
  "partial_ref": "string",
  "partial_revision": 0,
  "project_id": "string",
  "respondent_count": 0,
  "result_ref": "string",
  "run_id": "string",
  "stages": [
    {
      "check_progress": {},
      "checks_run": [
        "string"
      ],
      "checks_skipped": [
        "string"
      ],
      "duration_ms": 0,
      "flag_count": 0,
      "id": "string",
      "label": "string",
      "note": "string",
      "partial_ref": "string",
      "progress_pct": 0,
      "status": "string"
    }
  ],
  "started_at": "string",
  "status": "string",
  "tier_counts": {}
}

Shapes are generated from the schema with placeholder values. They are not configuration recommendations.