Portfolios

List portfolios

GET /api/v1/project/{projectId}/v1/portfolio

Credentials: API token or dashboard sign-in.

Every portfolio in this project. A portfolio is a named set of subjects scored together; each entry carries its portfolio_id, name, members (each with member_type and value) and whether it is the built-in portfolio that holds every subject (is_implicit). Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Create a portfolio

POST /api/v1/project/{projectId}/v1/portfolio

Credentials: API token or dashboard sign-in.

Creates a portfolio with a name and, optionally, its first members. Scoring begins immediately; until it finishes, the portfolio's state and rank answer 503. Requires project:portfolio:view and project:edit.

Parameters

Request body

application/json (required)

CreatePortfolioRequest

Responses

Example

curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio" \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '<JSON body>'

Get a portfolio

GET /api/v1/project/{projectId}/v1/portfolio/{portfolioId}

Credentials: API token or dashboard sign-in.

One portfolio by id: its name, members and settings. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Update a portfolio

PUT /api/v1/project/{projectId}/v1/portfolio/{portfolioId}

Credentials: API token or dashboard sign-in.

Renames a portfolio and/or replaces its members. name sets the name; members replaces the whole member list, each {"type": "subject" | "package", "value": ...}. A changed membership rescores the portfolio. The built-in portfolio (is_implicit) cannot be edited. Requires project:portfolio:view and project:edit.

Parameters

Request body

application/json (required)

UpdatePortfolioRequest

Responses

Example

curl -X PUT "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>" \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '<JSON body>'

Delete a portfolio

DELETE /api/v1/project/{projectId}/v1/portfolio/{portfolioId}

What it changes: Its scores and history stop being served. The subjects themselves are untouched.

Credentials: API token or dashboard sign-in.

Deletes a portfolio. It leaves the list and its reads answer 404; its subjects and their criticality ratings are untouched. The built-in portfolio (is_implicit) cannot be deleted. Requires project:portfolio:view and project:edit.

Parameters

Responses

Example

curl -X DELETE "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Get portfolio history

GET /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/history

Credentials: API token or dashboard sign-in.

The portfolio's scores over time: one row per score movement, each with its axis, score, band, what caused the change and when. The axis query parameter limits the rows to one of pqc, vuln or agility. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/history" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

List portfolio members

GET /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/member

Credentials: API token or dashboard sign-in.

The members of a portfolio, each a subject or a package. The built-in portfolio lists every subject in the project. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/member" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Add a member to a portfolio

POST /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/member

Credentials: API token or dashboard sign-in.

Adds one member, {"type": "subject" | "package", "value": ...}; a plain string is a subject. Adding a member that is already present changes nothing. The portfolio is rescored. The built-in portfolio (is_implicit) cannot be changed. Requires project:portfolio:view and project:edit.

Parameters

Request body

application/json (required)

MemberSpec

Responses

Example

curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/member" \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '<JSON body>'

Remove a member from a portfolio

DELETE /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/member/{value}

What it changes: The portfolio's scores are worked out again without this member.

Credentials: API token or dashboard sign-in.

Removes one member, named by its value in the path, with its kind in the type query parameter: subject (the default) or package. The portfolio is rescored. The built-in portfolio (is_implicit) cannot be changed. Requires project:portfolio:view and project:edit.

Parameters

Responses

Example

curl -X DELETE "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/member/<value>" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Get portfolio rank

GET /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/rank

Credentials: API token or dashboard sign-in.

The ranked list of fixes for a portfolio, best first, one page at a time. offset (default 0) and limit (default 50) query parameters choose the page; rows keep their overall rank number. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/rank" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Simulate portfolio fixes

POST /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/simulate

Credentials: API token or dashboard sign-in.

What the portfolio's score would be if the named fixes were applied. The body is one fix, a list of fixes, or {"fixes": [...]}. A fix names a row of the ranked list in item_key; on its own that means fixing everything on the row. Add finding_key to fix one finding of the row, or dependency (a library the row bundles) to upgrade that library, never both; upgrade_to sets the version to upgrade to, and defaults to the known fixed version. The answer holds the current and projected scores, marked as projected; add the rank=true query parameter to get the re-ranked fix list as well. Nothing is changed. Requires project:portfolio:view.

Parameters

Request body

The fixes to simulate

application/json (required)

SimulateFixes

Responses

Example

curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/simulate" \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '<JSON body>'

Get portfolio state

GET /api/v1/project/{projectId}/v1/portfolio/{portfolioId}/state

Credentials: API token or dashboard sign-in.

The portfolio's current score and its breakdown by axis and by subject, with the time it was computed. The ranked fix list is left out unless the rank=true query parameter asks for it; the rank endpoint serves it in pages. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/portfolio/<portfolioId>/state" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Regenerate a report

POST /api/v1/project/{projectId}/v1/report/{jobId}/regenerate

Credentials: API token or dashboard sign-in.

Asks for a new version of a report under the current report version. A posture report is rebuilt from the same data as of the same date. A survey's report is rebuilt by a new survey that reuses the analysis the survey already has, with no new upload. The old version stays readable. The answer's job_id is the job to follow: the new posture report, or for a survey's report the new survey; supersedes names the posture report or survey it replaces. A report is regenerated once: while its new version is being produced, and after it is ready, a further request answers 409. If the new version fails, or is still waiting to start after 30 minutes, you may ask again. Requires project:edit.

Parameters

Responses

Example

curl -X POST "https://api.spicelabs.io/api/v1/project/<projectId>/v1/report/<jobId>/regenerate" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

List subjects

GET /api/v1/project/{projectId}/v1/subject

Credentials: API token or dashboard sign-in.

Every subject in this project. A subject is a thing being scored, such as an application or a component; each carries its current criticality and when it was first and last seen. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/subject" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

List a subject's contents

GET /api/v1/project/{projectId}/v1/subject/{subject}/content

Credentials: API token or dashboard sign-in.

The items currently inside a subject, one page at a time. offset (default 0) and limit query parameters choose the page. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/subject/<subject>/content" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"

Rate a subject's criticality

PUT /api/v1/project/{projectId}/v1/subject/{subject}/criticality

Credentials: Dashboard sign-in only. API tokens are refused.

Records how important a subject is. The body carries value, one of high, medium, low or unclassified, and an optional rationale. The caller is recorded as the rater. Ratings are kept as a history and never overwritten, and every portfolio holding the subject is rescored. Only a dashboard session may call this, never an API token. Requires project:portfolio:rate.

Parameters

Request body

application/json (required)

RateCriticality

Responses

Example

curl -X PUT "https://api.spicelabs.io/api/v1/project/<projectId>/v1/subject/<subject>/criticality" \
  -H "Authorization: Bearer $SPICE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '<JSON body>'

Get criticality history

GET /api/v1/project/{projectId}/v1/subject/{subject}/criticality/history

Credentials: API token or dashboard sign-in.

Every criticality rating a subject has received, each with its value, the prior_value it replaced, who rated it, the rationale and when. A subject that has never been rated gives an empty list. Requires project:portfolio:view.

Parameters

Responses

Example

curl -X GET "https://api.spicelabs.io/api/v1/project/<projectId>/v1/subject/<subject>/criticality/history" \
  -H "Authorization: Bearer $SPICE_API_TOKEN"