Reference

Register app

Registers a target app and drives it to a testable state. No security test is auto-triggered — trigger tests explicitly via POST /apps//security-agent. Onboarding depends on the input: (a) URL only, no credentials, no spec (the DEFAULT, createTestAccounts not false) — the platform runs full autonomous onboarding like the console “Automatic” prompt: it creates test accounts (auto sign-up), validates logins, discovers roles, provisions RBAC accounts, maps the app and completes registration (response carries an onboarding handle). If it can’t sign up (no public sign-up / CAPTCHA / SSO / unreachable) it pauses and emails the caller rather than degrading to an unauthenticated test. (b) credentials and/or a spec supplied — the platform uses them and schedules the registration-completing run. (c) createTestAccounts=false with no spec — a browserless pass maps your API surface (pollable specExtraction handle) for an unauthenticated test. The app resource is created synchronously (201 + Location header) with registrationStatus IN_PROGRESS; poll GET /apps/ until registrationStatus is COMPLETED, then trigger a test. Registration is completed by onboarding, not by a security test. Supplied credentials are stored encrypted and never returned.

POST

apps

curl --request POST \
  --url https://api.perfai.ai/v1/apps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "Payments App",
  "appUrl": "https://payments.example.com"
}
'

{
  "appId": "<string>",
  "registrationStatus": "PENDING",
  "reason": "needs_login",
  "message": "We hit a snag — we're on it. Your results so far are saved.",
  "createdAt": "2023-11-07T05:31:56Z",
  "statusUrl": "<string>",
  "onboarding": {
    "mode": "auto-signup",
    "message": "<string>"
  },
  "specExtraction": {
    "taskId": "<string>",
    "state": "QUEUED",
    "statusUrl": "<string>"
  },
  "replaced": {
    "previousAppId": "<string>",
    "previousStatus": "PENDING"
  }
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

Authorizations

Authorization

string

header

required

JWT login token tied to your Perfai user (not a separate API key). Obtain it via POST /api/v1/auth/token with your username and password (use the returned id_token) — the same login the web console performs. Carries org, user, and role; short-lived.

Body

application/json

appUrl

string<uri>

required

Base URL of the application under test (http/https).

Maximum string length: 2048

label

string

Human-readable app name. Optional — defaults to the host of appUrl when omitted.

Maximum string length: 150

spec

string | null

Advanced. A URL to your app's OpenAPI definition (or inline content) — provide it to skip discovery. Omit to let the platform map your API surface. REST/GraphQL is detected automatically.

Maximum string length: 2000000

tenantOneCredentials

object[]

Credentials for the primary tenant, one entry per role. Optional — omit to have the platform auto-create accounts (default), or for unauthenticated / public apps (with createTestAccounts=false). Each is stored as an encrypted auth record; admin/user/rbac roles are derived from the set.

Maximum array length: 20

Show child attributes

tenantTwoCredentials

object[]

Credentials for a second tenant, used for cross-tenant (BOLA) testing. Optional.

Maximum array length: 20

Show child attributes

createTestAccounts

boolean

default:true

Whether the platform autonomously creates test accounts (auto sign-up) when no credentials are supplied — mirroring the console "Automatic" onboarding. Default true. Only applies when BOTH credentials AND spec are omitted; ignored otherwise. Set false to register for an unauthenticated (public-endpoint-only) test — no accounts are created, so authenticated / RBAC / cross-tenant (BOLA) tests will not run.

skipEndpoints

string[]

Endpoints to exclude from every security test of this app, as "method:path" entries. Use it to keep destructive or disruptive operations out of scope — account deletion, logout, payment capture. Method may be a verb or "*"; path may use "**" as a glob. Applied as a blocklist, only when no include-filter is in force for the run.

Maximum array length: 200

Maximum string length: 500

Pattern: ^(\*|[A-Za-z]+):[^:]+$

Example:

[
  "DELETE:/api/v1/users/{id}",
  "POST:/api/v1/payments/capture",
  "*:/internal/**"
]

headers

string[]

Extra HTTP headers sent with requests to the application under test, as "Name: value" entries — a gateway API key, a tenant selector, a feature flag the app requires. Sent as supplied; never returned by the API.

Maximum array length: 50

Maximum string length: 4096

Example:

[
  "X-Api-Key: 9f8c1e02-5b6a-4b1e",
  "X-Tenant-Id: acme"
]

maxSteps

integer

How many exploration steps the platform may take while mapping your API surface. Raise it for large apps with deep navigation or many nested workflows — a mapping missing endpoints is the usual reason to. Higher values map more thoroughly but lengthen registration. Applies only when the platform maps the app itself (no spec supplied). Omit to use your organization's configured value, which itself defaults to 150.

Required range: 1 <= x <= 1000

Example:

300

Response

App registered; onboarding in progress.

appId

string

registrationStatus

enum<string>

Returned as IN_PROGRESS. The platform completes onboarding on its own; poll GET /apps/{appId} until COMPLETED. Registration is NOT completed by a security test — a test requires COMPLETED as a precondition.

Available options:

PENDING,

IN_PROGRESS,

NEEDS_INPUT,

COMPLETED,

COMPLETED_PARTIAL,

INTERRUPTED,

CANCELLED

reason

enum<string> | null

Why a task or app is in its state. Null when the state needs no explanation. New values may be added; show message for any you do not recognise.

Available options:

needs_login,

needs_roles,

needs_access,

needs_app_url,

needs_spec,

app_unreachable,

out_of_credits,

no_response,

paused,

partial_coverage,

our_side_error,

dependency_lost,

null

message

string

One sentence for the user — the same wording the console shows for this state.

Example:

"We hit a snag — we're on it. Your results so far are saved."

createdAt

string<date-time>

statusUrl

string

onboarding

object | null

Present on the default auto-signup path.

Show child attributes

specExtraction

object | null

Present only on the createTestAccounts=false no-spec path. Absent when a spec/credentials were supplied, auto-signup ran, or the vision run could not be enqueued.

Show child attributes

replaced

object | null

Present when this registration replaced a previous, unusable app for the same URL (INTERRUPTED/NEEDS_INPUT/COMPLETED_PARTIAL/CANCELLED/PENDING, or a stuck IN_PROGRESS). A COMPLETED or actively-onboarding app is reused via 409 instead.

Show child attributes

curl --request POST \
  --url https://api.perfai.ai/v1/apps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "Payments App",
  "appUrl": "https://payments.example.com"
}
'

{
  "appId": "<string>",
  "registrationStatus": "PENDING",
  "reason": "needs_login",
  "message": "We hit a snag — we're on it. Your results so far are saved.",
  "createdAt": "2023-11-07T05:31:56Z",
  "statusUrl": "<string>",
  "onboarding": {
    "mode": "auto-signup",
    "message": "<string>"
  },
  "specExtraction": {
    "taskId": "<string>",
    "state": "QUEUED",
    "statusUrl": "<string>"
  },
  "replaced": {
    "previousAppId": "<string>",
    "previousStatus": "PENDING"
  }
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

{
  "type": "<string>",
  "title": "<string>"
}

Getting Started

Core Concepts

Hybrid Deployment

Changelog

Register app

Authorizations

Body

Response