Reqflo Dev Docs

Reqflo Dev Docs

API reference and CLI docs in one Fumadocs site.

Developer docs

API reference

API reference and CLI docs live together on this Fumadocs page.

OpenAPI JSON

Introduction

Reqflo API

External API contract for Reqflo clients, automation, and the Reqflo CLI.

Productionhttps://app.reqflo.com
Local developmenthttp://localhost:3100
AuthenticationAuthorization: Bearer YOUR_SECRET_TOKEN

API folder

Scans

Ingest API scans from external clients.

POST/api/scans/ingest

Ingest an API scan

Accepts normalized OpenAPI scan output from the Reqflo CLI. The organization is resolved from the API key and must not be included in the request body.

Operation IDingestScan
Request body
serviceobjectrequired
+ Show Child Attributes
namestringmin 1 ...120required
specobjectrequired
+ Show Child Attributes
hashstringmin 64 ...64required
formatstringenum: openapirequired
versionstring...80
titlestring...200
endpointsobject[]...2000required
+ Show Child Attributes
methodstringenum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACErequired
pathstring...1000required
operationIdstring | null...200required
tagsstring[]...20required
summarystring | null...300required
findingsobject[]...500required
+ Show Child Attributes
codestring...120required
severitystringenum: info, low, medium, high, criticalrequired
messagestring...500required
methodstring | nullenum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE, required
pathstring | null...1000required
Responses
201Scan accepted and persisted.
acceptedbooleanrequired
organization_idobjectUuiduuidrequired
service_idobjectUuiduuidrequired
api_spec_idobjectUuiduuidrequired
scan_run_idobjectUuiduuidrequired
endpoint_countinteger>= 0required
finding_countinteger>= 0required
created_servicebooleanrequired
scan_run_urlstring
400The request did not pass validation.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
401Authentication is required or invalid.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
403The authenticated principal lacks permission.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
413Scan payload is too large.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
POST/api/scans/ingestShell Curl⌄
1curl https://app.reqflo.com/api/scans/ingest \2  --request POST \3  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \4  --header 'Content-Type: application/json' \5  --data '{6  "service": {7    "name": "Billing API"8  },9  "spec": {10    "hash": "8f14e45fceea167a5a36dedd4bea2543a6f6f6a4fc5f1fc9e2b192d7ab1b03c2",11    "format": "openapi",12    "version": "3.1.0",13    "title": "Billing API"14  },15  "endpoints": [16    {17      "method": "POST",18      "path": "/charges",19      "operationId": "createCharge",20      "tags": [21        "Payments"22      ],23      "summary": "Create charge"24    }25  ],26  "findings": []27}'

API folder

API Keys

Create, list, inspect, and revoke API keys.

GET/api/api-keys

List API keys

Operation IDlistApiKeys
Parameters
NameInTypeRequired
organizationIdqueryobjectrequired
Responses
200API key metadata and scopes.
apiKeysobject[]required
+ Show Child Attributes
idobjectUuiduuidrequired
namestringrequired
prefixstringrequired
organizationIdobjectUuiduuidrequired
ownerPrincipalTypestring | nullenum: user, service_account,
ownerPrincipalIdstring | nulluuid
ownerDisplayNamestring | null
createdBystring | null
scopesobject[]required
+ Show Child Attributes
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject
expiresAtstring | nulldate-time
lastUsedAtstring | nulldate-time
revokedAtstring | nulldate-time
createdAtobjectIsoDateTimedate-timerequired
statusstringenum: active, expired, revokedrequired
principalobjectPrincipalSummaryrequired
+ Show Child Attributes
typestringrequired
organizationIdobjectUuiduuidrequired
400The request did not pass validation.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
401Authentication is required or invalid.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
403The authenticated principal lacks permission.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
GET/api/api-keysShell Curl⌄
1curl https://app.reqflo.com/api/api-keys \2  --request GET \3  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
POST/api/api-keys

Create an API key

Creates a scoped key and returns the raw key once. Store the raw key immediately.

Operation IDcreateApiKey
Request body
organizationIdobjectUuiduuidrequired
namestring...120required
ownerPrincipalTypestringenum: user, service_accountrequired
ownerPrincipalIdstring | nulluuid
scopesstring | object[]min items 1required
expiresAtstring | nulldate-time
Responses
201API key created.
apiKeyobjectApiKeyrequired
+ Show Child Attributes
idobjectUuiduuidrequired
namestringrequired
prefixstringrequired
organizationIdobjectUuiduuidrequired
ownerPrincipalTypestring | nullenum: user, service_account,
ownerPrincipalIdstring | nulluuid
ownerDisplayNamestring | null
createdBystring | null
scopesobject[]required
+ Show Child Attributes
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject
expiresAtstring | nulldate-time
lastUsedAtstring | nulldate-time
revokedAtstring | nulldate-time
createdAtobjectIsoDateTimedate-timerequired
statusstringenum: active, expired, revokedrequired
rawKeystringrequired

Returned once. Store it immediately.

warningstringrequired
400The request did not pass validation.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
401Authentication is required or invalid.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
403The authenticated principal lacks permission.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
POST/api/api-keysShell Curl⌄
1curl https://app.reqflo.com/api/api-keys \2  --request POST \3  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \4  --header 'Content-Type: application/json' \5  --data '{6  "organizationId": "00000000-0000-0000-0000-000000000000",7  "name": "string",8  "ownerPrincipalType": "user",9  "ownerPrincipalId": "00000000-0000-0000-0000-000000000000",10  "scopes": [11    "string"12  ],13  "expiresAt": "2026-01-01T00:00:00.000Z"14}'
GET/api/api-keys/{apiKeyId}

Get API key metadata

Operation IDgetApiKey
Parameters
NameInTypeRequired
apiKeyIdpathobjectrequired
organizationIdqueryobjectrequired
Responses
200API key metadata.
apiKeyobjectApiKeyrequired
+ Show Child Attributes
idobjectUuiduuidrequired
namestringrequired
prefixstringrequired
organizationIdobjectUuiduuidrequired
ownerPrincipalTypestring | nullenum: user, service_account,
ownerPrincipalIdstring | nulluuid
ownerDisplayNamestring | null
createdBystring | null
scopesobject[]required
+ Show Child Attributes
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject
expiresAtstring | nulldate-time
lastUsedAtstring | nulldate-time
revokedAtstring | nulldate-time
createdAtobjectIsoDateTimedate-timerequired
statusstringenum: active, expired, revokedrequired
400The request did not pass validation.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
401Authentication is required or invalid.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
403The authenticated principal lacks permission.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
404The requested resource was not found.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
GET/api/api-keys/{apiKeyId}Shell Curl⌄
1curl https://app.reqflo.com/api/api-keys/{apiKeyId} \2  --request GET \3  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
POST/api/api-keys/{apiKeyId}/revoke

Revoke an API key

Operation IDrevokeApiKey
Parameters
NameInTypeRequired
apiKeyIdpathobjectrequired
Request body
organizationIdobjectUuiduuidrequired
Responses
200API key revoked.
apiKeyobjectApiKeyrequired
+ Show Child Attributes
idobjectUuiduuidrequired
namestringrequired
prefixstringrequired
organizationIdobjectUuiduuidrequired
ownerPrincipalTypestring | nullenum: user, service_account,
ownerPrincipalIdstring | nulluuid
ownerDisplayNamestring | null
createdBystring | null
scopesobject[]required
+ Show Child Attributes
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject
expiresAtstring | nulldate-time
lastUsedAtstring | nulldate-time
revokedAtstring | nulldate-time
createdAtobjectIsoDateTimedate-timerequired
statusstringenum: active, expired, revokedrequired
400The request did not pass validation.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
401Authentication is required or invalid.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
403The authenticated principal lacks permission.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
404The requested resource was not found.
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired
POST/api/api-keys/{apiKeyId}/revokeShell Curl⌄
1curl https://app.reqflo.com/api/api-keys/{apiKeyId}/revoke \2  --request POST \3  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \4  --header 'Content-Type: application/json' \5  --data '{6  "organizationId": "00000000-0000-0000-0000-000000000000"7}'

Models

Schemas

Named payloads and response models in the OpenAPI contract.

Uuid

string
stringuuid

IsoDateTime

string
stringdate-time

ErrorResponse

object
errorobject
+ Show Child Attributes
codestringrequired
messagestringrequired

ScanIngestionPayload

object
serviceobjectrequired
+ Show Child Attributes
namestringmin 1 ...120required
specobjectrequired
+ Show Child Attributes
hashstringmin 64 ...64required
formatstringenum: openapirequired
versionstring...80
titlestring...200
endpointsobject[]...2000required
+ Show Child Attributes
methodstringenum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACErequired
pathstring...1000required
operationIdstring | null...200required
tagsstring[]...20required
summarystring | null...300required
findingsobject[]...500required
+ Show Child Attributes
codestring...120required
severitystringenum: info, low, medium, high, criticalrequired
messagestring...500required
methodstring | nullenum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE, required
pathstring | null...1000required

NormalizedEndpoint

object
methodstringenum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACErequired
pathstring...1000required
operationIdstring | null...200required
tagsstring[]...20required
summarystring | null...300required

NormalizedFinding

object
codestring...120required
severitystringenum: info, low, medium, high, criticalrequired
messagestring...500required
methodstring | nullenum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE, required
pathstring | null...1000required

ScanIngestionResult

object
acceptedbooleanrequired
organization_idobjectUuiduuidrequired
service_idobjectUuiduuidrequired
api_spec_idobjectUuiduuidrequired
scan_run_idobjectUuiduuidrequired
endpoint_countinteger>= 0required
finding_countinteger>= 0required
created_servicebooleanrequired
scan_run_urlstring

CreateApiKeyRequest

object
organizationIdobjectUuiduuidrequired
namestring...120required
ownerPrincipalTypestringenum: user, service_accountrequired
ownerPrincipalIdstring | nulluuid
scopesstring | object[]min items 1required
expiresAtstring | nulldate-time

CreatedApiKeyResult

object
apiKeyobjectApiKeyrequired
+ Show Child Attributes
idobjectUuiduuidrequired
namestringrequired
prefixstringrequired
organizationIdobjectUuiduuidrequired
ownerPrincipalTypestring | nullenum: user, service_account,
ownerPrincipalIdstring | nulluuid
ownerDisplayNamestring | null
createdBystring | null
scopesobject[]required
+ Show Child Attributes
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject
expiresAtstring | nulldate-time
lastUsedAtstring | nulldate-time
revokedAtstring | nulldate-time
createdAtobjectIsoDateTimedate-timerequired
statusstringenum: active, expired, revokedrequired
rawKeystringrequired

Returned once. Store it immediately.

warningstringrequired

ApiKey

object
idobjectUuiduuidrequired
namestringrequired
prefixstringrequired
organizationIdobjectUuiduuidrequired
ownerPrincipalTypestring | nullenum: user, service_account,
ownerPrincipalIdstring | nulluuid
ownerDisplayNamestring | null
createdBystring | null
scopesobject[]required
+ Show Child Attributes
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject
expiresAtstring | nulldate-time
lastUsedAtstring | nulldate-time
revokedAtstring | nulldate-time
createdAtobjectIsoDateTimedate-timerequired
statusstringenum: active, expired, revokedrequired

ApiKeyScope

object
idstring
permissionstringrequired
resourceTypestring | null...80
resourceIdstring | nulluuid
serviceIdstring | nulluuid
environmentIdstring | nulluuid
workflowIdstring | nulluuid
resourceConstraintsobject

PrincipalSummary

object
typestringrequired
organizationIdobjectUuiduuidrequired

CLI

Scan OpenAPI specs from the command line

The current CLI surface is focused on scan ingestion. It reads a local OpenAPI JSON or YAML file, extracts normalized endpoints, and submits the result to Reqflo with API key authentication.

Install

The CLI package is named @reqflo/cli. During local development, link it from the repository:

cd reqflo-cli
npm install
npm link

reqflo --help

Once published, install it globally from npm:

npm install -g @reqflo/cli

Configure authentication

Create an API key in Reqflo with the scopes required for scan ingestion. The scan endpoint resolves the organization from the API key, so do not send an organization ID in the payload.

export REQFLO_API_KEY=rf_live_...
export REQFLO_API_URL=https://app.reqflo.com

The scan flow typically needs scans:create, services:read, services:create, services:update, endpoints:read, and endpoints:write.

Scan command

Use reqflo scan to upload a local OpenAPI spec.

reqflo scan \
  --service "Billing API" \
  --spec ./openapi.yaml \
  --api-key rf_live_... \
  --api-url https://app.reqflo.com
OptionDescription
--service <name>Service name to create or update in Reqflo.
--spec <path>Local OpenAPI JSON or YAML file to scan.
--api-key <key>Reqflo scoped API key. You can also set REQFLO_API_KEY.
--api-url <url>Reqflo backend URL. You can also set REQFLO_API_URL or REQFLO_BASE_URL.

Output

A successful scan returns the created scan run, endpoint count, and finding count.

Scan ingested: 68a3129a-7f6c-4f5d-9bb9-b1cf61f492c1
Result URL: https://app.reqflo.com/scan-runs/68a3129a-7f6c-4f5d-9bb9-b1cf61f492c1
Endpoints: 24; findings: 0

Common errors

  • API key required: pass --api-key or set REQFLO_API_KEY.
  • --spec is required: provide a local OpenAPI JSON or YAML file.
  • OpenAPI spec is too large: the CLI currently limits spec files to 10 MB.
  • scan ingestion failed: inspect the API response code and message from the Reqflo backend.