Endpoint REST

Accanto a GraphQL ci sono alcuni semplici endpoint HTTP: il flusso di accesso dal browser, le sonde di health check e il download dei report PDF. Tutto il resto passa da GraphQL.

URL di base

https://vulnara-gw.rso.dev

GET/auth/oauth2

Start browser sign-in

Redirects the browser to the Vulnara sign-in page. After sign-in the browser comes back to the callback below.

Risposte

Nome	Descrizione
302	Redirect to the sign-in page.

Richiesta

curl "https://vulnara-gw.rso.dev/auth/oauth2"

GET/auth/oauth2/callback

Finish browser sign-in

The sign-in page redirects here. Vulnara exchanges the code for tokens and hands them to the web app. You do not call this yourself.

Parametri

Nome	Tipo	Descrizione
codeObbligatorio	query
stateObbligatorio	query

Risposte

Nome	Descrizione
302	Redirect to the web app, signed in, or to the sign-in failure page.

Richiesta

curl "https://vulnara-gw.rso.dev/auth/oauth2/callback"

POST/auth/oauth2/refresh

Refresh an access token

Swap a refresh token for a new access token and refresh token.

Risposte

Nome	Descrizione
200	New tokens.
400	The refresh token is missing, expired or revoked. Sign in again.

Richiesta

curl -X POST "https://vulnara-gw.rso.dev/auth/oauth2/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<refresh token>"}'

GET/auth/signup

Start free sign-up

Redirects the browser to the Vulnara sign-up page. Once the account is created, the browser signs in to the web app.

Risposte

Nome	Descrizione
302	Redirect to the sign-up page.

Richiesta

curl "https://vulnara-gw.rso.dev/auth/signup"

Chat

POST/chat/message

Send a chat message

Sends one message to the chat assistant in the web app and streams its answer as Server-Sent Events. The assistant answers for the workspace named in X-Tenant, with your access in it.

Parametri

Nome	Tipo	Descrizione
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	A stream of Server-Sent Events. Each delta event carries the next piece of the answer as {"text"}. The stream ends with one done event or one error event. done carries the whole answer: with mode llm, reply holds the assistant's answer; with mode fallback, the workspace has used its daily chat allowance and matches lists documentation passages, each with its sourceUrl, instead of a generated answer. error carries {"message"} for a failure after the stream started.
400	The message is missing or empty.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
502	The chat service is unavailable. Try again.

Richiesta

curl -X POST "https://vulnara-gw.rso.dev/chat/message" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -H "Content-Type: application/json" \
  -d '{"message":"Which repositories have critical findings?"}'

Health

GET/health/live

Liveness

Answers while the API is running.

Risposte

Nome	Descrizione
200	Running.

Richiesta

curl "https://vulnara-gw.rso.dev/health/live"

GET/health/ready

Readiness

Answers 200 when the API can serve requests.

Risposte

Nome	Descrizione
200	Ready.
503	Not ready yet.

Richiesta

curl "https://vulnara-gw.rso.dev/health/ready"

Reports

GET/reports/network/{id}

Network report

A PDF report for one network.

Parametri

Nome	Tipo	Descrizione
idObbligatorio	path	Id of the network.
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	The report as a PDF download.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
404	The item does not exist in this workspace.
429	Too many report downloads. Reports are limited to 20 a minute per caller, with a burst of 5, across all report routes. Wait for the number of seconds in the Retry-After header.
502	The report could not be generated. Try again.

Richiesta

curl "https://vulnara-gw.rso.dev/reports/network/<id>" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -o report.pdf

GET/reports/repository/{id}

Repository report

A PDF report for one repository.

Parametri

Nome	Tipo	Descrizione
idObbligatorio	path	Id of the repository.
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	The report as a PDF download.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
404	The item does not exist in this workspace.
429	Too many report downloads. Reports are limited to 20 a minute per caller, with a burst of 5, across all report routes. Wait for the number of seconds in the Retry-After header.
502	The report could not be generated. Try again.

Richiesta

curl "https://vulnara-gw.rso.dev/reports/repository/<id>" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -o report.pdf

GET/reports/scan/{id}

Scan report

A PDF report for one scan result.

Parametri

Nome	Tipo	Descrizione
idObbligatorio	path	Id of the scan result.
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	The report as a PDF download.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
404	The item does not exist in this workspace.
429	Too many report downloads. Reports are limited to 20 a minute per caller, with a burst of 5, across all report routes. Wait for the number of seconds in the Retry-After header.
502	The report could not be generated. Try again.

Richiesta

curl "https://vulnara-gw.rso.dev/reports/scan/<id>" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -o report.pdf

GET/reports/summary

Security summary report

A PDF summary of the security posture of the whole workspace.

Parametri

Nome	Tipo	Descrizione
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	The report as a PDF download.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
404	The item does not exist in this workspace.
429	Too many report downloads. Reports are limited to 20 a minute per caller, with a burst of 5, across all report routes. Wait for the number of seconds in the Retry-After header.
502	The report could not be generated. Try again.

Richiesta

curl "https://vulnara-gw.rso.dev/reports/summary" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -o report.pdf

GET/reports/web-target/{id}

Web target report

A PDF report for one web target.

Parametri

Nome	Tipo	Descrizione
idObbligatorio	path	Id of the web target.
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	The report as a PDF download.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
404	The item does not exist in this workspace.
429	Too many report downloads. Reports are limited to 20 a minute per caller, with a burst of 5, across all report routes. Wait for the number of seconds in the Retry-After header.
502	The report could not be generated. Try again.

Richiesta

curl "https://vulnara-gw.rso.dev/reports/web-target/<id>" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -o report.pdf

GET/reports/workspace/{id}

Git workspace report

A PDF report for one git workspace: an organisation, group or user on your git provider.

Parametri

Nome	Tipo	Descrizione
idObbligatorio	path	Id of the git workspace.
X-Tenant	header	Workspace id. Optional when you belong to one workspace only.

Risposte

Nome	Descrizione
200	The report as a PDF download.
401	Missing or invalid bearer token.
403	You are not a member of the requested workspace.
404	The item does not exist in this workspace.
429	Too many report downloads. Reports are limited to 20 a minute per caller, with a burst of 5, across all report routes. Wait for the number of seconds in the Retry-After header.
502	The report could not be generated. Try again.

Richiesta

curl "https://vulnara-gw.rso.dev/reports/workspace/<id>" \
  -H "Authorization: Bearer $VULNARA_TOKEN" \
  -H "X-Tenant: $VULNARA_TENANT" \
  -o report.pdf

Endpoint REST

Sign-in

GET/auth/oauth2

Risposte

GET/auth/oauth2/callback

Parametri

Risposte

POST/auth/oauth2/refresh

Risposte

GET/auth/signup

Risposte

Chat

POST/chat/message

Parametri

Risposte

Health

GET/health/live

Risposte

GET/health/ready

Risposte

Reports

GET/reports/network/{id}

Parametri

Risposte

GET/reports/repository/{id}

Parametri

Risposte

GET/reports/scan/{id}

Parametri

Risposte

GET/reports/summary

Parametri

Risposte

GET/reports/web-target/{id}

Parametri

Risposte

GET/reports/workspace/{id}

Parametri

Risposte