Updated
API v1 Reference
The /api/v1 surface is a curated, additive re-export of the existing API. Breaking changes will be introduced under a new major version.
Base URL:
https://app.lyrashieldai.com/api/v1. Authenticate with a workspace API key in the Authorization: Bearer <key> header.Download the OpenAPI 3.1 spec as JSON: openapi.json
Endpoints (37)
GET/agent-approvalsList agent approvals
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
status | query | no | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of agent approvals400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/agent-approvalsCreate an agent approval
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
201— Agent approval created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/agent-approvals/{id}/approveApprove an agent action
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Agent approval approved400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/agent-approvals/{id}/denyDeny an agent action
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Agent approval denied400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/findingsList findings
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
targetId | query | no | string |
observedInScanId | query | no | string |
scanId | query | no | string |
severity | query | no | string |
status | query | no | string |
verified | query | no | string |
category | query | no | string |
q | query | no | string |
stats | query | no | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of findings400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/findings/{id}Get a finding
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Responses
200— Finding details400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
PATCH/findings/{id}Update a finding
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Finding updated400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/findings/{id}/fix-proposalsCreate a fix proposal
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Fix proposal created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/findings/{id}/retestsQueue a retest
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
201— Retest queued400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/fix-proposalsList fix proposals
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
findingId | query | no | string |
status | query | no | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of fix proposals400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/fix-proposals/{id}/create-prCreate a pull request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
400— Bad request401— Unauthorized403— Forbidden404— Not found409— Pull request creation is blocked pending server-generated patch evidence422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/launch-readinessLaunch readiness report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
targetId | query | no | string |
Responses
200— Launch readiness summary400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/projectsList projects
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of projects400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/projectsCreate a project
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Project created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/reportsList reports
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of reports400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/reportsCreate a report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
201— Report created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/reports/{id}Get a report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Responses
200— Report details400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/reports/{id}Share or revoke a report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Report action completed400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/reports/{id}/downloadDownload a report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Responses
200— Report HTML400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/retestsList retests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
findingId | query | no | string |
status | query | no | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of retests400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/scansList scans
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
targetId | query | no | string |
status | query | no | string |
cursor | query | no | string |
limit | query | no | string |
If-None-Match | header | no | string |
Responses
200— List of scans304— Not Modified400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/scansCreate a scan
Creates a recorded scan with a server-owned immutable execution plan. `workflow` selects REVIEW_TARGET (default) or REVIEW_CHANGES (repository diff review — requires `baseRef`, optional `headRef`); `attachmentIds` reference previously staged workspace artifacts. AUTHENTICATED_ASSESSMENT is a gated staging beta: it requires `authorizationRef` (a recorded scoped authorization) and returns SCAN_WORKFLOW_UNAVAILABLE (400) unless the deployment enables it for this workspace/target. Advisory local checks (CLI check-diff, GitHub Action gate) are never equivalent to this recorded path.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
201— Scan created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/scans/{id}Get a scan
Returns the scan with its recorded execution plan (workflow, scope, resolved immutable source revisions), events, result-manifest checksum and coverage receipts.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
If-None-Match | header | no | string |
Responses
200— Scan details304— Not Modified400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/scans/{id}Cancel a scan
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Scan cancelled400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/scans/{id}/artifacts/sarifImport a SARIF report into a scan
Imports third-party SARIF 2.1.0 detections into an existing scan. Imported findings are tagged external_import and never count as scanner coverage or independently verified findings. Requires a write-scoped API key or browser session; delegated OAuth connections are refused.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— SARIF findings imported400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict413— SARIF payload exceeds the 5 MiB limit422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/scans/eligibilityAdvisory scan eligibility preflight
Read-only advisory check: whether POST /scans would currently admit the requested review — same permission, plan, domain-proof and entitlement gates, evaluated without any trial, billing, scan or audit mutation. `allowed:false` is a successful read carrying a structured denial (`code`, `message`, `blockers`), not an error. POST /scans re-checks authoritatively at creation; a pass here never guarantees admission. `attachmentIds` is a repeated query parameter.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
targetId | query | yes | string |
goal | query | yes | — |
mode | query | yes | — |
workflow | query | no | string |
baseRef | query | no | string |
headRef | query | no | string |
attachmentIds | query | no | array |
authorizationRef | query | no | string |
Responses
200— Eligibility verdict400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/schedulesList schedules
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
targetId | query | no | string |
enabled | query | no | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of schedules400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/schedulesCreate a schedule
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
201— Schedule created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
DELETE/schedules/{id}Delete a schedule
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Responses
200— Schedule deleted400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/schedules/{id}Get a schedule
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Responses
200— Schedule details400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
PATCH/schedules/{id}Update a schedule
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Schedule updated400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/targetsList targets
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
projectId | query | no | string |
cursor | query | no | string |
limit | query | no | string |
Responses
200— List of targets400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/targetsCreate a target
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Target created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
DELETE/targets/{id}Delete a target (soft delete)
Marks the target deleted and frees its plan target slot. Scans, findings, verdicts, reports and evidence are retained in the workspace. Refused while a scan for the target is queued or running.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Responses
204— Target deleted400— Bad request401— Unauthorized403— Forbidden404— Target not found or already deleted409— Target has a queued or running scan422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
PATCH/targets/{id}Update a target
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Target updated400— Bad request401— Unauthorized403— Forbidden404— Not found409— Repository ref is immutable after the first scan422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
GET/workspacesList workspaces
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Responses
200— List of workspaces400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable
POST/workspacesCreate a workspace
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workspaceId | query | yes | string |
Request body: application/json
Responses
200— Workspace created400— Bad request401— Unauthorized403— Forbidden404— Not found409— Conflict422— Validation failed429— Rate limited500— Internal server error503— Service temporarily unavailable