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
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
{
"filename": "string",
"size_bytes": 0
}
{
"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
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
curl --fail-with-body -X POST "$CM_API_BASE/datasets/uploads/{upload_id}/complete" \
-H "Authorization: Bearer $CM_API_KEY"
{
"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
curl --fail-with-body -X GET "$CM_API_BASE/datasets/limits" \
-H "Authorization: Bearer $CM_API_KEY"
{
"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
curl --fail-with-body -X GET "$CM_API_BASE/datasets/{dataset_id}" \
-H "Authorization: Bearer $CM_API_KEY"
{
"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
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
{
"dataset_id": "string"
}
{
"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
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/projects/{project_id}/configuration" \
-H "Authorization: Bearer $CM_API_KEY"
{
"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
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
{
"draft": {
"catalogue_version": "string",
"guards": {}
},
"expected_revision": 0
}
{
"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
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
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
{
"items": [
{
"configuration_revision": 0,
"item_id": "string",
"project_id": "string"
}
]
}
{
"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
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/batches/{batch_id}" \
-H "Authorization: Bearer $CM_API_KEY"
{
"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
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/runs/{run_id}" \
-H "Authorization: Bearer $CM_API_KEY"
{
"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.
Get an owner-authorized link to the run's full result
GET/surveyguard/runs/{run_id}/result-link
Requires surveyguard:read
Parameters
run_id path, required
string
Request body
No request body.
Responses
200Successful Response
application/json
An owner-authorized download location, without loading the artifact body.
url string · required
Presigned object-storage URL. Fetch it directly without application credentials; do not cache or log this bearer capability.
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
curl --fail-with-body -X GET "$CM_API_BASE/surveyguard/runs/{run_id}/result-link" \
-H "Authorization: Bearer $CM_API_KEY"
{
"url": "string"
}
Shapes are generated from the schema with placeholder values. They are not configuration recommendations.