API and MCP
Surveys
Analysis runs over an upload: start one, report its progress, run it again
Start a survey
POST /api/v1/project/{projectId}/survey
Credentials: Spice Pass only.
Registers a survey before its upload begins, so it is visible from the moment work starts. jobType is INVENTORY_SURVEY or RUNTIME_SURVEY; tag, jsonTags, target and notes are optional and shown with the survey. The Idempotency-Key header is required: a repeat with the same key returns the same parent_id. Only a Spice Pass may call this, as the Spice Labs CLI does; pass the returned parent_id as parentId when starting the upload.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | The project's id. |
Idempotency-Key required | header | string |
Request body
application/json (required)
Responses
| Status | Description | Body |
|---|---|---|
201 | The new survey: parent_id, submission_timestamp and its step ids when known. | SurveyStarted |
400 | jobType is not INVENTORY_SURVEY or RUNTIME_SURVEY, or the Idempotency-Key header is missing. | Error |
401 | The credential is missing, expired, revoked, or is not a Spice Pass. | Error |
403 | The token is valid but not allowed to do this. | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/survey" \
-H "Authorization: Bearer $SPICE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '<JSON body>'Report survey progress
POST /api/v1/project/{projectId}/survey/{surveyId}/status
Credentials: Spice Pass only.
Records progress on one step of a survey. subJobId names a step of the survey in the path; status is PENDING, RUNNING, COMPLETED, FAILED or SKIPPED; progress (0 to 100), message, metadata and analyzeStats are optional and merged onto the step. Only a Spice Pass may call this, as the Spice Labs CLI does while it analyses and uploads.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | The project's id. |
surveyId required | path | string (uuid) | |
Idempotency-Key | header | string |
Request body
application/json (required)
Responses
| Status | Description | Body |
|---|---|---|
204 | The step is updated. | |
400 | subJobId is not a step of this survey, status is unknown, or analyzeStats was sent both at the top level and inside metadata. | Error |
401 | The credential is missing, expired, revoked, or is not a Spice Pass. | Error |
403 | The token is valid but not allowed to do this. | Error |
404 | No survey with this id exists in this project. | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/survey/<surveyId>/status" \
-H "Authorization: Bearer $SPICE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '<JSON body>'Regenerate a survey
POST /api/v1/project/{projectId}/v1/survey/{surveyId}/regenerate
Credentials: API token or dashboard sign-in.
Runs a survey again from the upload it already has, with no new upload. A new survey is created whose supersedes points at this one; if this survey, or any of its steps, has not finished, it is marked SKIPPED. With no body, only the reports are produced again from the earlier analysis. With a body, skipAnalyze decides: true produces only the reports, while false or leaving it out, as in {}, repeats the analysis too. The Idempotency-Key header is required: a repeat with the same key returns the same new survey. Requires project:edit.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | The project's id. |
surveyId required | path | string (uuid) | |
Idempotency-Key required | header | string | A unique key for this request; repeating it returns the stored response |
Request body
application/json (optional)
Responses
| Status | Description | Body |
|---|---|---|
201 | The new survey: parent_id, supersedes, submission_timestamp and its step ids in sub_job_ids. | SurveyRegenerated |
400 | The job is not a survey, the survey has no completed upload to reuse, or the Idempotency-Key header is missing. | Error |
401 | The token is missing, expired, revoked or of the wrong kind. | Error |
403 | The token is valid but not allowed to do this. | Error |
404 | No survey with this id exists in this project. | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/v1/survey/<surveyId>/regenerate" \
-H "Authorization: Bearer $SPICE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '<JSON body>'