> ## Documentation Index > Fetch the complete documentation index at: https://docs.perfai.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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/{appId}/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/{appId} 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /apps openapi: 3.1.1 info: title: Perfai Security API version: 1.1.0 description: > Partner-facing REST API for automating Perfai security testing: register apps, trigger security tests and vision (browser-automation) runs, poll run status, and retrieve vulnerability findings. All endpoints are JWT-authenticated and scoped to the caller's organization; cross-tenant access returns 404 (never 403) to prevent enumeration. Errors follow RFC 9457 Problem Details. servers: - url: https://api.perfai.ai/v1 description: Perfai cloud - url: https://api.{customerDomain}/v1 description: On-premise deployment variables: customerDomain: default: example.com security: - bearerAuth: [] tags: - name: Apps description: App catalog — list, register, and poll registration. - name: Security Agent description: Trigger security tests and poll their lifecycle. - name: Vision Agent description: >- Trigger vision (browser-automation) runs and poll their lifecycle. Always browserless. - name: Vulnerabilities description: Retrieve security findings. - name: Reports description: List an app's security reports and download them as PDF. - name: Tasks description: Poll any asynchronous operation started by this API. paths: /apps: post: tags: - Apps summary: Register app description: > Registers a target app and drives it to a testable state. No security test is auto-triggered — trigger tests explicitly via POST /apps/{appId}/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/{appId} 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. operationId: registerApp requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterApp' examples: minimal: summary: URL only — autonomous onboarding with auto sign-up (default) value: label: Payments App appUrl: https://payments.example.com unauthenticated: summary: Unauthenticated / public app (no account creation) value: label: Payments App appUrl: https://payments.example.com createTestAccounts: false withCredentials: summary: Registration with tenant credentials value: label: Payments App appUrl: https://payments.example.com tenantOneCredentials: - role: Admin username: admin@example.com password: •••••••• - role: User username: user@example.com password: •••••••• tenantTwoCredentials: - role: Admin username: tenant2-admin@example.com password: •••••••• specFirst: summary: Advanced — supply your own API spec value: label: Payments App appUrl: https://payments.example.com spec: https://payments.example.com/openapi.json responses: '201': description: App registered; onboarding in progress. headers: Location: description: URL of the created app resource (poll for registrationStatus). schema: type: string content: application/json: schema: $ref: '#/components/schemas/RegisterAppResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '409': description: > A usable app (COMPLETED, or actively onboarding) already exists for this URL — app-already-registered, includes the existing appId to reuse. A dead app (FAILED/CANCELLED, or long-stuck IN_PROGRESS) is replaced with a fresh 201 instead (see the `replaced` field). If an app for this URL exists that was not registered through this API, it is never replaced — app-registered-outside-api. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': $ref: '#/components/responses/RateLimited' '500': description: registration-failed — the app was not registered; retry the request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: > onboarding-unavailable — this deployment does not have the onboarding workflow engine enabled, so autonomous sign-up cannot run. Register with a `spec` or with tenant credentials instead. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' components: schemas: RegisterApp: type: object required: - appUrl additionalProperties: false properties: label: type: string maxLength: 150 description: >- Human-readable app name. Optional — defaults to the host of appUrl when omitted. appUrl: type: string format: uri maxLength: 2048 description: Base URL of the application under test (http/https). spec: type: - string - 'null' maxLength: 2000000 description: >- 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. tenantOneCredentials: type: array maxItems: 20 items: $ref: '#/components/schemas/RoleCredential' description: > 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. tenantTwoCredentials: type: array maxItems: 20 items: $ref: '#/components/schemas/RoleCredential' description: >- Credentials for a second tenant, used for cross-tenant (BOLA) testing. Optional. createTestAccounts: type: boolean default: true description: > 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: type: array maxItems: 200 items: type: string maxLength: 500 pattern: ^(\*|[A-Za-z]+):[^:]+$ description: > 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. example: - DELETE:/api/v1/users/{id} - POST:/api/v1/payments/capture - '*:/internal/**' headers: type: array maxItems: 50 items: type: string maxLength: 4096 description: > 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. example: - 'X-Api-Key: 9f8c1e02-5b6a-4b1e' - 'X-Tenant-Id: acme' maxSteps: type: integer minimum: 1 maximum: 1000 description: > 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. example: 300 RegisterAppResponse: type: object properties: appId: type: string registrationStatus: allOf: - $ref: '#/components/schemas/RegistrationStatus' description: > 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. createdAt: type: string format: date-time statusUrl: type: string onboarding: oneOf: - $ref: '#/components/schemas/Onboarding' - type: 'null' description: Present on the default auto-signup path. specExtraction: oneOf: - $ref: '#/components/schemas/SpecExtraction' - type: 'null' description: >- 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. replaced: oneOf: - $ref: '#/components/schemas/Replaced' - type: 'null' description: > Present when this registration replaced a previous, unusable app for the same URL (FAILED/CANCELLED/PENDING, or a stuck IN_PROGRESS). A COMPLETED or actively-onboarding app is reused via 409 instead. Problem: type: object description: RFC 9457 Problem Details. properties: type: type: string description: Error type URI, e.g. https://perfai.ai/errors/app-already-registered title: type: string additionalProperties: true RoleCredential: type: object required: - role - username - password additionalProperties: false description: > One authentication for a tenant: a role plus its username/password login. The API style (REST vs GraphQL) is detected automatically. properties: role: type: string maxLength: 100 description: >- Role this login represents (e.g. "Admin", "User", or a custom RBAC role). Drives privilege derivation and role-based access testing. username: type: string maxLength: 320 description: Username or email used to authenticate. password: type: string maxLength: 1024 description: Password. Encrypted at rest; never logged or returned. loginUrl: type: string format: uri maxLength: 2048 description: URL where these credentials authenticate. Defaults to the app URL. RegistrationStatus: type: string enum: - PENDING - IN_PROGRESS - COMPLETED - FAILED - CANCELLED description: Onboarding state. COMPLETED, FAILED, and CANCELLED are terminal. Onboarding: type: object description: >- Present when the platform started autonomous onboarding (auto sign-up) because no credentials/spec were supplied and createTestAccounts was not false. properties: mode: type: string example: auto-signup description: Onboarding mode driving this registration. message: type: string description: Human-readable note on what the platform is doing. SpecExtraction: type: object description: >- Present only when createTestAccounts=false and no spec was supplied and an API-surface mapping run was enqueued. properties: taskId: type: string state: $ref: '#/components/schemas/VisionRunState' statusUrl: type: string description: Poll this until the vision run reaches COMPLETED. Replaced: type: object description: The previous unusable app for this URL that this registration replaced. properties: previousAppId: type: string previousStatus: type: string description: FAILED, CANCELLED, PENDING, or a stuck IN_PROGRESS. VisionRunState: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - CANCELLED responses: BadRequest: description: Validation error. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: Missing or expired JWT. InsufficientCredits: description: >- Organization credit balance exhausted (billing-enabled deployments only). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: Caller's role does not permit this operation (Viewer is read-only). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' RateLimited: description: >- Rate limit exceeded. Back off and retry after the Retry-After header value. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > 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. ````