Xbow Findings API
Endpoints for viewing and managing findings. All endpoints require an _organization_ API key.
OpenAPI Specification
openapi: 3.1.0
info:
description: "\n# Versioning\n\nThe API is in public preview. This is a stable version that exposes the most common functionality of the platform. If your use case is not covered, tell us so that we can prioritize work for future releases.\n\nAll API endpoints require the `X-XBOW-API-Version` header to be set to a supported version. Requests without a version header will be rejected with a `400 Bad Request` response.\n\n## Version Lifecycle\n\nAPI versions follow a `YYYY-MM-DD` naming convention (for example, `2026-04-01`). During the public preview, each version is supported, without breaking changes, for a minimum of 4 months from its release date. The support window for new versions will increase as the API matures.\n\n| Version | Release Date | End of Life |\n|------------|--------------|-------------|\n| next | Rolling | N/A |\n| 2026-07-01 | 2026-07-01 | 2026-11-01 |\n| 2026-06-01 | 2026-06-01 | 2026-10-01 |\n| 2026-04-01 | 2026-04-01 | 2026-07-01 |\n\n## The \"next\" Version\n\nThe `next` version provides early access to upcoming API changes. Use it in non-production environments to test and prepare for the next stable release.\n\n- Changes are pushed to `next` as they stabilize\n- `next` becomes the next stable version upon release\n- Breaking changes may occur in `next` before a stable release\n\n## End of Life (EOL)\n\nWhen a version reaches its end-of-life date:\n\n- **API requests** to that version will fail with a `400 Bad Request` response\n- **Webhook subscriptions** for that version will stop emitting events\n\nMigrate to a supported version before the EOL date to avoid service disruption. Also update webhooks to a supported version.\n\n## Changes from 2026-06-01 to 2026-07-01\n\n### Finding workflow metadata\n\nFindings now carry customer-controlled workflow metadata, independent of the XBOW-owned lifecycle fields (state, severity, CVSS):\n\n- `externalWorkflowState`: your own tracking state for the finding.\n- `externalTicketReference`: a reference to an external ticket. May only be present alongside an `externalWorkflowState`.\n\nA new endpoint updates these fields:\n\n- `PATCH /api/v1/findings/:findingId` — Update a finding's `externalWorkflowState` and `externalTicketReference`. Omitted fields are left unchanged; send `null` to clear a field.\n\nThese fields also appear in `GET /api/v1/findings/{findingId}`, `GET /api/v1/assets/{assetId}/findings`, and `finding.changed` webhook payloads for subscriptions pinned to `2026-07-01`.\n\n# Accessing the API\n\nThe API is available at `https://console.xbow.com/api/v1/`. All endpoints require authentication via an API key provided in the `Authorization: Bearer <token>` header.\n\n**Note:** For Lightspeed organizations, the API is available in read-only mode. That is, only `GET` endpoints are available.\n\n## Generate a personal access token (PAT)\n\n1. Log into your XBOW dashboard at https://console.xbow.com with administrator access to the organization you want to generate an API key for.\n1. Click your profile icon in the top right corner and select **Settings**.\n1. In the left sidebar, click **Personal Access Tokens**.\n1. Click **Generate new token**.\n1. Provide a name and select the scope for the token, that is, the organization you want to use it with.\n1. Click **Create**.\n1. Copy and securely store your key (it won't be shown again).\n\nStore API keys securely using environment variables or secret managers. Never commit keys to version control. Rotate keys periodically and revoke compromised keys immediately.\n\n## API request headers\n\nAll API requests require two headers: your API key for authentication and the API version you want to use. For example:\n\n```curl\ncurl -X GET \"https://console.xbow.com/api/v1/assets/{assetId}/findings\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"X-XBOW-API-Version: 2026-07-01\" \\\n -H \"Content-Type: application/json\"\n```\n\n## Error responses\n\nIn addition to the responses described with each endpoint, the API may also return the following responses:\n\n- `400 Bad Request`: the request was malformed or contained invalid parameters, including missing version header.\n- `401 Unauthorized`: missing an API key or the provided API key is invalid.\n- `403 Forbidden`: the API key is valid, but the user does not have permission to access the requested resource.\n- `429 Too Many Requests`: exceeded rate limit, try again with exponential backoff.\n- `500 Internal Server Error`: an unexpected error occurred, try again with exponential backoff.\n\nThe error response body will be in the following format:\n\n```json\n{\n \"code\": \"ERR_ERROR_TYPE\",\n \"error\": \"Error Type\",\n \"message\": \"Detailed error message\"\n}\n```\n\n# Pagination & Rate Limiting\n\n## Pagination\n\nList endpoints use cursor-based pagination. Use the `limit` query parameter to control page size (1-100, default 20) and the `after` parameter to fetch subsequent pages using the cursor from a previous response.\n\nResponses include an `items` array and a `nextCursor` field:\n\n```json\n{\n \"items\": [...],\n \"nextCursor\": \"eyJpZCI6IjEyMyJ9\"\n}\n```\n\nTo fetch the next page, pass the `nextCursor` value as the `after` parameter in your next request. When `nextCursor` is `null`, there are no more results.\n\n## Rate Limiting\n\nAPI requests are subject to rate limiting. If you receive a `429 Too Many Requests` response, implement exponential backoff before retrying.\n\n"
title: XBOW Assessments Findings API
version: '2026-07-01'
servers:
- description: Default
url: https://console.xbow.com/
- description: Multi SAAS - Europe data resident instance
url: https://console.eu.xbow.com/
- description: Multi SAAS - Asia Pacific data resident instance
url: https://console.sg.xbow.com/
tags:
- description: 'Endpoints for viewing and managing findings.
All endpoints require an _organization_ API key.'
name: Findings
paths:
/api/v1/assets/{assetId}/findings:
get:
description: 'Lists all findings for an asset.
Supports pagination via `limit` and `after` query parameters.'
parameters:
- in: query
name: limit
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
- in: query
name: after
required: false
schema:
type: string
- in: path
name: assetId
required: true
schema:
type: string
- description: API version to use for this request
in: header
name: X-XBOW-API-Version
required: true
schema:
enum:
- '2026-07-01'
example: '2026-07-01'
type: string
responses:
'200':
content:
application/json:
schema:
example:
items:
- createdAt: '2025-01-01T00:00:00Z'
externalTicketReference: JIRA-4821
externalWorkflowState: in-progress
id: 123e4567-e89b-12d3-a456-426614174000
name: Example Finding
severity: critical
state: open
updatedAt: '2025-01-01T00:00:00Z'
nextCursor: eyJjcmVhdGVkQXQiOiIyMDI1LTAxLTAxVDAwOjAwOjAwWiIsImlkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0=
properties:
items:
items:
properties:
createdAt:
format: date-time
type: string
externalTicketReference:
anyOf:
- maxLength: 1024
type: string
- type: 'null'
description: Customer-supplied reference to a ticket in an external system (e.g. a Jira key), or null if not set.
externalWorkflowState:
anyOf:
- description: 'Customer-controlled workflow state for tracking remediation in your own process. Independent of the XBOW-owned `state`:
- `not-started`: remediation has not begun
- `in-progress`: remediation is underway
- `completed`: remediation is complete
`null` means the workflow state has never been set, which is distinct from `not-started`.'
enum:
- completed
- in-progress
- not-started
type: string
- type: 'null'
description: Customer-controlled workflow state, or null if never set.
id:
type: string
name:
type: string
severity:
description: 'Severity level of the finding:
- `critical`: Highest severity, requires immediate attention
- `high`: High severity, should be addressed soon
- `medium`: Medium severity
- `low`: Low severity
- `informational`: Informational only, no immediate action required
'
enum:
- critical
- high
- informational
- low
- medium
type: string
state:
description: 'Current state of the finding:
- `open`: new finding discovered by XBOW
- `challenged`: finding challenged by user
- `confirmed`: finding challenged by user, but confirmed by XBOW as a true positive, cannot be challenged again
- `invalid`: finding challenged by user, and confirmed by XBOW as a false positive, cannot be challenged again
- `fixed`: finding fixed by user
'
enum:
- challenged
- confirmed
- fixed
- invalid
- open
type: string
updatedAt:
format: date-time
type: string
required:
- createdAt
- externalTicketReference
- externalWorkflowState
- id
- name
- severity
- state
- updatedAt
type: object
type: array
nextCursor:
type: string
required:
- items
type: object
description: Default Response
'400':
content:
application/json:
schema:
properties:
code:
description: A constant for machines
enum:
- FST_ERR_VALIDATION
type: string
error:
description: A human readable string for the constant
enum:
- Bad Request
type: string
message:
description: A human readable message
type: string
requestId:
description: A unique identifier for the request
type: string
required:
- code
- error
- message
- requestId
type: object
description: Default Response
security:
- Authorization: []
summary: List findings
tags:
- Findings
/api/v1/findings/{findingId}:
get:
description: Gets a specific finding
parameters:
- in: path
name: findingId
required: true
schema:
type: string
- description: API version to use for this request
in: header
name: X-XBOW-API-Version
required: true
schema:
enum:
- '2026-07-01'
example: '2026-07-01'
type: string
responses:
'200':
content:
application/json:
schema:
example:
assetId: 123e4567-e89b-12d3-a456-426614174000
createdAt: '2025-01-01T00:00:00Z'
cvss:
'3.1':
fields:
A: N
AC: L
AV: N
C: L
I: L
PR: N
S: C
UI: R
score: 6.1
vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N
cwe: CWE-79
evidence: ''' OR ''1''=''1'' --'
externalTicketReference: JIRA-4821
externalWorkflowState: in-progress
id: 123e4567-e89b-12d3-a456-426614174000
impact: This finding can lead to X, Y, Z
mitigations: To mitigate this, do A, B, C
name: Example Finding
organizationId: 123e4567-e89b-12d3-a456-426614174000
recipe: '1. First do this
2. Then do this
3. Finally do this'
severity: critical
state: open
summary: Finding _details_
updatedAt: '2025-01-01T00:00:00Z'
properties:
assetId:
type: string
createdAt:
format: date-time
type: string
cvss:
additionalProperties:
properties:
fields:
description: Decomposed CVSS vector components
properties:
A:
enum:
- H
- L
- N
type: string
AC:
enum:
- H
- L
type: string
AR:
enum:
- H
- L
- M
- X
type: string
AV:
enum:
- A
- L
- N
- P
type: string
C:
enum:
- H
- L
- N
type: string
CR:
enum:
- H
- L
- M
- X
type: string
E:
enum:
- F
- H
- P
- U
- X
type: string
I:
enum:
- H
- L
- N
type: string
IR:
enum:
- H
- L
- M
- X
type: string
MA:
enum:
- H
- L
- N
- X
type: string
MAC:
enum:
- H
- L
- X
type: string
MAV:
enum:
- A
- L
- N
- P
- X
type: string
MC:
enum:
- H
- L
- N
- X
type: string
MI:
enum:
- H
- L
- N
- X
type: string
MPR:
enum:
- H
- L
- N
- X
type: string
MS:
enum:
- C
- U
- X
type: string
MUI:
enum:
- N
- R
- X
type: string
PR:
enum:
- H
- L
- N
type: string
RC:
enum:
- C
- R
- U
- X
type: string
RL:
enum:
- O
- T
- U
- W
- X
type: string
S:
enum:
- C
- U
type: string
UI:
enum:
- N
- R
type: string
required:
- A
- AC
- AV
- C
- I
- PR
- S
- UI
type: object
score:
description: CVSS score from 0.0 to 10.0
type: number
vector:
description: CVSS vector string, e.g. CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N
type: string
required:
- fields
- score
- vector
type: object
description: CVSS scores for this finding, keyed by version. Not all findings have a CVSS score.
type: object
cwe:
description: CWE identifier for this finding (e.g. CWE-79). Not all findings have a CWE.
type: string
evidence:
description: Evidence demonstrating the vulnerability such as a proof-of-concept exploit or request/response logs
type: string
externalTicketReference:
anyOf:
- maxLength: 1024
type: string
- type: 'null'
description: Customer-supplied reference to a ticket in an external system (e.g. a Jira key), or null if not set.
externalWorkflowState:
anyOf:
- description: 'Customer-controlled workflow state for tracking remediation in your own process. Independent of the XBOW-owned `state`:
- `not-started`: remediation has not begun
- `in-progress`: remediation is underway
- `completed`: remediation is complete
`null` means the workflow state has never been set, which is distinct from `not-started`.'
enum:
- completed
- in-progress
- not-started
type: string
- type: 'null'
description: Customer-controlled workflow state, or null if never set.
id:
type: string
impact:
description: Markdown description of the impact of the finding
type: string
mitigations:
description: Markdown description of possible mitigations for the finding
type: string
name:
type: string
organizationId:
type: string
recipe:
description: Markdown instructions on how to reproduce the finding
type: string
severity:
description: 'Severity level of the finding:
- `critical`: Highest severity, requires immediate attention
- `high`: High severity, should be addressed soon
- `medium`: Medium severity
- `low`: Low severity
- `informational`: Informational only, no immediate action required
'
enum:
- critical
- high
- informational
- low
- medium
type: string
state:
description: 'Current state of the finding:
- `open`: new finding discovered by XBOW
- `challenged`: finding challenged by user
- `confirmed`: finding challenged by user, but confirmed by XBOW as a true positive, cannot be challenged again
- `invalid`: finding challenged by user, and confirmed by XBOW as a false positive, cannot be challenged again
- `fixed`: finding fixed by user
'
enum:
- challenged
- confirmed
- fixed
- invalid
- open
type: string
summary:
description: Markdown high-level overview of the finding
type: string
updatedAt:
format: date-time
type: string
required:
- assetId
- createdAt
- evidence
- externalTicketReference
- externalWorkflowState
- id
- impact
- mitigations
- name
- organizationId
- recipe
- severity
- state
- summary
- updatedAt
type: object
description: Default Response
'400':
content:
application/json:
schema:
properties:
code:
description: A constant for machines
enum:
- FST_ERR_VALIDATION
type: string
error:
description: A human readable string for the constant
enum:
- Bad Request
type: string
message:
description: A human readable message
type: string
requestId:
description: A unique identifier for the request
type: string
required:
- code
- error
- message
- requestId
type: object
description: Default Response
'404':
content:
application/json:
schema:
properties:
code:
description: A constant for machines
enum:
- ERR_NOT_FOUND
type: string
error:
description: A human readable string for the constant
enum:
- Not Found
type: string
message:
description: A human readable message
type: string
requestId:
description: A unique identifier for the request
type: string
required:
- code
- error
- message
- requestId
type: object
description: The requested resource was not found
security:
- Authorization: []
summary: Get finding
tags:
- Findings
patch:
description: 'Updates customer-controlled workflow metadata on a finding. Only `externalWorkflowState` and `externalTicketReference` may be set; these are independent of the XBOW-owned lifecycle fields (state, severity, CVSS). Omitted fields are left unchanged; send `null` to clear a field.
An `externalTicketReference` may only be present alongside an `externalWorkflowState`: the workflow state may be set on its own, but a ticket reference may not. A request whose result would leave a ticket reference without a workflow state is rejected with a 400.'
parameters:
- in: path
name: findingId
required: true
schema:
type: string
- description: API version to use for this request
in: header
name: X-XBOW-API-Version
required: true
schema:
enum:
- '2026-07-01'
example: '2026-07-01'
type: string
requestBody:
content:
application/json:
schema:
properties:
externalTicketReference:
anyOf:
- maxLength: 1024
type: string
- type: 'null'
description: New external ticket reference. Send null to clear. Omit to leave unchanged. May only be set alongside an externalWorkflowState — a finding cannot carry a ticket reference without a workflow state.
externalWorkflowState:
anyOf:
- description: 'Customer-controlled workflow state for tracking remediation in your own process. Independent of the XBOW-owned `state`:
- `not-started`: remediation has not begun
- `in-progress`: remediation is underway
- `completed`: remediation is complete
`null` means the workflow state has never been set, which is distinct from `not-started`.'
enum:
- completed
- in-progress
- not-started
type: string
- type: 'null'
type: object
required: true
responses:
'200':
content:
application/json:
schema:
example:
assetId: 123e4567-e89b-12d3-a456-426614174000
createdAt: '2025-01-01T00:00:00Z'
cvss:
'3.1':
fields:
A: N
AC: L
AV: N
C: L
I: L
PR: N
S: C
UI: R
score: 6.1
vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N
cwe: CWE-79
evidence: ''' OR ''1''=''1'' --'
externalTicketReference: JIRA-4821
externalWorkflowState: in-progress
id: 123e4567-e89b-12d3-a456-426614174000
impact: This finding can lead to X, Y, Z
mitigations: To mitigate this, do A, B, C
name: Example Finding
organizationId: 123e4567-e89b-12d3-a456-426614174000
recipe: '1. First do this
2. Then do this
3. Finally do this'
severity: critical
state: open
summary: Finding _details_
updatedAt: '2025-01-01T00:00:00Z'
properties:
assetId:
type: string
createdAt:
format: date-time
type: string
cvss:
additionalProperties:
properties:
fields:
description: Decomposed CVSS vector components
properties:
A:
enum:
- H
- L
- N
type: string
AC:
enum:
- H
- L
type: string
AR:
enum:
- H
- L
- M
- X
type: string
AV:
enum:
- A
- L
- N
- P
type: string
C:
enum:
- H
- L
- N
type: string
CR:
enum:
- H
- L
- M
- X
type: string
E:
enum:
- F
- H
- P
- U
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xbow/refs/heads/main/openapi/xbow-findings-api-openapi.yml