API and MCP
Reports
Survey reports: their contents, summaries, searches, comparisons and exports
List stale projections
GET /api/v1/project/{projectId}/v1/projection/stale
Lists the rendered documents (PDF, spreadsheet, slides and so on) that are out of date: the latest document for each survey, report type and format whose inputs have moved on since it was made, for example because the analysis logic or a document template has a newer version, or because a survey it was built from has been replaced. Each entry names what changed. Regenerate or re-render the report to bring a document up to date. Pass parentId to check a single survey. An empty list means everything is current. Requires project:admin.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
parentId | query | string (uuid) | Only check documents from this survey and its regenerated versions |
Responses
| Status | Description | Body |
|---|---|---|
200 | Out-of-date documents; empty when everything is current | StaleResponse |
400 | The template version map is not valid JSON | 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 |
500 | A fault on our side. | Error |
503 | The service is temporarily unavailable; try again shortly | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/projection/stale" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Get a full report
GET /api/v1/project/{projectId}/v1/report/{jobId}
Downloads the complete report document as JSON. For a cryptography bill of materials report this is the CycloneDX document; for other reports it is the full report with every section. The document can be large, so it is streamed; use the summary, section and search operations to read parts of it instead. Answers 400 when the job ID is not a UUID, and 404 when no report has this ID. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | The full report document as a JSON object, streamed. Its layout depends on the report type, so no fixed schema is given | object |
400 | The job ID is not a UUID | 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 report has this ID | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>" \
-H "Authorization: Bearer $SPICE_API_TOKEN"List a report's export formats
GET /api/v1/project/{projectId}/v1/report/{jobId}/export
Lists the formats a report can be downloaded in right now. json is always available; pdf, xlsx, csv, html and pptx appear once that document has been produced. Download one with the export operation. Answers 400 when the job ID is not a UUID. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | The formats ready to download | ExportFormats |
400 | The job ID is not a UUID | 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 | An id in the path, other than the organization or project, names nothing visible to the token. | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/export" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Export a report
GET /api/v1/project/{projectId}/v1/report/{jobId}/export/{format}
Downloads a report in one format. json returns the full report document wrapped as {"data": <report>}. pdf, xlsx, csv, html and pptx return the rendered file as an attachment named report.<format>, with the matching content type. A rendered format is produced after the report completes; until then the request answers 404, so retry later or check the list of export formats. Answers 400 when the format is not one of these or the job ID is not a UUID. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
format required | path | string | Export format: json, pdf, xlsx, csv, html, pptx |
Responses
| Status | Description | Body |
|---|---|---|
200 | The report in the requested format, streamed: for json a JSON object {"data": <report>}; otherwise the file's bytes (application/pdf, spreadsheet, text/csv, text/html or presentation) | |
400 | The format or the job ID is not valid | 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 | The report does not exist, or this format has not been produced yet | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/export/<format>" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Get an export's provenance
GET /api/v1/project/{projectId}/v1/report/{jobId}/export/{format}/provenance
Returns the record of how a rendered document was produced: the report and survey it came from, the uploaded bundle, the versions of every input it was made with, and when it was rendered. Answers 400 when the format is not one of json, pdf, xlsx, csv, html or pptx, or the job ID is not a UUID, and 404 when no provenance has been recorded for this format. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
format required | path | string | Export format: json, pdf, xlsx, csv, html, pptx |
Responses
| Status | Description | Body |
|---|---|---|
200 | The provenance record | ExportProvenance |
400 | The format or the job ID is not valid | 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 provenance has been recorded for this format | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/export/<format>/provenance" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Search a report
GET /api/v1/project/{projectId}/v1/report/{jobId}/search
Finds report entries whose package URL, name or explanation contains the search text, ignoring case, across every section. Returns up to 200 matches, each marked with the section it came from. Answers 400 when query is missing or empty, or the job ID is not a UUID, and 404 when no report has this ID. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
query required | query | string | The text to look for in each entry's package URL, name and explanation |
Responses
| Status | Description | Body |
|---|---|---|
200 | Matching entries, at most 200 | array of SearchMatch |
400 | The query is missing, or the job ID is not a UUID | 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 report has this ID | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/search?query=<query>" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Get a page of a report section
GET /api/v1/project/{projectId}/v1/report/{jobId}/section/{section}
Returns one page of a report section's entries, with the section's total so you can page through it with offset and limit. The section names a report has are listed in its summary. A section that is not a list of entries is returned whole, as stored, without the page wrapper. Answers 400 when the job ID is not a UUID, and 404 when the report or the section does not exist. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
section required | path | string | The section name, as listed in the report summary's sections, for example red, yellow, transition or green |
offset | query | integer | Starting index (default 0) |
limit | query | integer | Page size, 1 to 10000 (default 1000) |
Responses
| Status | Description | Body |
|---|---|---|
200 | A page of the section's entries | SectionPage |
400 | The job ID is not a UUID | 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 | The report or the section does not exist | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/section/<section>" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Get a report summary
GET /api/v1/project/{projectId}/v1/report/{jobId}/summary
Returns a report's headline figures (for example how many algorithms fall in each risk section), the tag and type of the survey it was built from, when it was produced, and the list of sections it has. Answers 400 when the job ID is not a UUID, and 404 when no report has this ID. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
jobId required | path | string (uuid) | The report's job ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | The report summary | ReportSummary |
400 | The job ID is not a UUID | 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 report has this ID | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/summary" \
-H "Authorization: Bearer $SPICE_API_TOKEN"Compare two reports
GET /api/v1/project/{projectId}/v1/report/compare
Compares a baseline report (from) with another report (to), finding by finding across all sections, and returns what was added, what was removed, what moved to a different section, and how many findings stayed where they were. Use it to see the effect of a change between two surveys. Answers 400 when from or to is missing or not a UUID, and 404 when either report does not exist. Requires project:view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
projectId required | path | string (uuid) | |
from required | query | string | Job ID of the baseline report |
to required | query | string | Job ID of the report to compare against the baseline |
Responses
| Status | Description | Body |
|---|---|---|
200 | The differences between the two reports | ReportComparison |
400 | from or to is missing or not a UUID | 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 | One or both reports do not exist | Error |
500 | A fault on our side. | Error |
503 | The project's data is temporarily unreachable; code says why. | Error |
Example
curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/compare?from=<from>&to=<to>" \
-H "Authorization: Bearer $SPICE_API_TOKEN"