Skip to main content
The API drives Perfai Security programmatically: register an app, trigger security and vision runs, poll for completion, and read findings — all over REST with a JWT bearer token. Every request goes to one base URL, https://api.perfai.ai/v1 (self-hosted deployments swap in their own host), and carries an Authorization: Bearer <token> header. This guide covers the concepts and workflows behind those calls — how onboarding works, how to scope a scan, and how to read findings — the parts the raw endpoint definitions don’t explain. For the exact parameters, request and response schemas, and a try-it console for every endpoint, use the interactive Reference. To get a token and run your first test end to end, start with the Overview quickstart; the Overview also documents authentication, rate limits, the run state machine, pagination, the error format, and a complete CI-gate example.
Machine-readable contract. The full OpenAPI 3.1.1 spec is served at https://api.perfai.ai/v1/openapi.yaml — import it into Postman, an SDK generator, or any API tooling. The Reference is that spec, rendered.

​
Onboarding your app

POST /v1/apps (Register app) registers a target and drives it to a testable state. Perfai onboards it for you from the inputs you send — how much you send picks the path:
  • URL only — the default. Send just appUrl and Perfai runs full autonomous onboarding: it maps your API surface, creates test accounts for you (auto sign-up), validates the logins, and discovers roles. This is what lets a URL-only registration run authenticated, role-based, and cross-tenant tests rather than a shallow unauthenticated one — and it finishes by running one initial security test, so first findings are ready as soon as onboarding completes.
  • You bring credentials. Supply tenantOneCredentials (and tenantTwoCredentials for cross-tenant testing) and Perfai maps your surface using your accounts instead of signing up. This path does not run an initial test — trigger one yourself once the app is registered.
  • createTestAccounts: false. Perfai maps your surface but provisions no accounts — an unauthenticated, public-endpoint-only test.
Registration runs asynchronously. Poll GET /v1/apps/{appId} (Get app) until registrationStatus is COMPLETED, then trigger tests. Onboarding time depends heavily on the app — auto sign-up is the slowest path — so use a generous timeout and don’t treat a still-IN_PROGRESS app as stalled.
If Perfai can’t sign up — no public sign-up, a CAPTCHA, an SSO wall, or an unreachable URL — it pauses and emails you rather than silently continuing unauthenticated. The app stays IN_PROGRESS; provide accounts via POST /v1/apps/{appId}/account-setup (Run Account Setup), or re-register with tenantOneCredentials, to continue.

​
Tenants and roles

Two credential concepts drive the authorization tests, and they are not the same thing:
  • A tenant is a customer or account boundary inside your application — two separate customer organizations, say. Giving a second tenant’s logins in tenantTwoCredentials lets Perfai test whether one tenant can reach another’s data: BOLA (Broken Object Level Authorization).
  • A role is the permission level a login holds — Admin versus User. Providing several roles lets Perfai test RBAC (role-based access control): whether a lower-privilege role can perform higher-privilege actions.
Credentials travel over TLS, are stored encrypted, and are never logged or returned. The API style — REST or GraphQL — is detected automatically; you don’t declare it.

​
Scoping a scan

Three optional fields on POST /v1/apps tune how Perfai scans. All are safe to omit.

​
Excluding endpoints

skipEndpoints keeps chosen endpoints out of every test of the app. Reach for it before pointing Perfai at anything you can’t freely exercise — account deletion, logout, payment capture, bulk imports, anything that emails your users. Each entry is method:path:
The method is an HTTP verb or * for any verb; the path may use ** as a wildcard — *:/internal/** excludes everything under /internal.
Use exactly one colon per entry — DELETE:/api/v1/users/{id}, not DELETE /api/v1/users/{id}. A malformed entry is rejected at registration by design: silently skipping nothing would be more dangerous than a clear error.

​
Sending extra headers

headers adds HTTP headers to every request Perfai makes against your app, on top of whatever the credentials supply — a gateway API key, a tenant selector, or a feature flag your app needs to respond at all. Each entry is Name: value:

​
Controlling mapping depth

maxSteps caps how many exploration steps Perfai takes while mapping your API surface (1–1000). Raise it when mapping misses endpoints — large apps, deep navigation, or many nested workflows. Higher values map more thoroughly but lengthen registration. Omit it to use your organization’s configured value (150 by default).

​
Running tests and reading findings

Once registrationStatus is COMPLETED:
  1. Trigger a test — POST /v1/apps/{appId}/security-agent (Run Security Agent) returns a taskId immediately and runs asynchronously.
  2. Poll the task — GET /v1/tasks/{taskId} (Get task status) until state is terminal. See the test state machine for the states and a back-off strategy.
  3. Read findings — GET /v1/apps/{appId}/vulnerabilities (Get vulnerabilities).
The vulnerabilities response leads with a status that tells you where the app stands:
  • COMPLETED — findings are in data, paginated. Filter with severity, isFixed, isDismissed, or a search term.
  • RUN_IN_PROGRESS — a test is running; wait for it rather than reading stale findings.
  • NO_RUNS — no test has run yet.
Read NO_RUNS as “not tested yet,” never as “no vulnerabilities found.” An app registered with your own tenantOneCredentials or with createTestAccounts: false stays at NO_RUNS until you trigger a test — those paths don’t run one automatically. Call Run Security Agent to start one.

​
The finding object

Each finding carries the same detail the Perfai dashboard shows. Only id, label, and severity appear on every finding; every other field is conditional — present only when the scan produced a value, and omitted from the JSON otherwise (absent rather than null), so treat them as optional. path and method are present for endpoint-specific findings and absent for app-level ones — a missing security header, say. The Get vulnerabilities page in the Reference lists every field.
Every finding’s label is one of Perfai’s security categories, aligned to the OWASP API Security Top 10. The current set:API Governance / Inventory, BOLA – Cross-Role Access, BOLA – Cross-Tenant Role Access, BOLA – Same-Tenant Ownership Bypass, BOLA – Same-Tenant Write Without Read Access, Broken Access Control (BAC) - Inconsistent Permissions, Broken Authentication (Expired Token), Broken Authentication (Invalid Credentials), Broken Authentication (Invalid Token), Broken Authentication (No Token), Broken CORS Policy, Broken Data Access (BDA) - Inconsistent Permissions, Broken Date Range Limit, Broken Function Level Authorization, Broken Logout, Broken Object Level Authorization (BOLA), Broken Pagination Limit, Broken Project-Level Authorization (BPLA), Broken Resource-Level Authorization (BRLA), Broken Tenant-Level Authorization (BTLA), Broken Token Claim Manipulation, Broken Token Revocation, Broken Token Signature Verification, Client Side Request Forgery, Cost Evasion / Audit Data Tampering, Credential Exposure via URL Parameters, Cross-Application Token Acceptance, Cross-Environment Token Acceptance, Cross-Site Scripting (XSS), Cross-Tenant Data Contamination, Cross-Tenant Takeover, Cross-User Data Contamination, Data Access Authorization Anomaly, Data Access Breaking Change, Debug Endpoint Exposed, Enumerable Resource ID, Excessive Token Data Exposure, Exposed Credentials, Hidden Sensitive Data in Authorized Responses, Input Validation, JNDI Injection, Malicious File Acceptance, Missing HSTS Header, Missing Token Audience Claim, Missing Token Issuer Claim, Missing Token Revocation, Nested Sensitive Data Exposure, NoSQL Injection, Non-JWT Token Format, Open HTTP Redirection, Pagination Missing, Privilege Escalation, Prompt Injection, RBAC Matrix Validation, SBAC Matrix Validation, SQL Injection, SSL Certificate Expiration (<15 days), Search Data Leak, Search Data Leak (Authorized), Security Configuration Missing, Self-Signed SSL Certificate, Sensitive Business Flows / Rate Limiting, Sensitive Data Exposure, Sensitive Data in Error & Metadata Responses, Server Side Request Forgery (SSRF), Session Hijacking, Shadow Data, TLS Version Below 1.2, Token & Data Security (Read Operations), Token & Data Security (Write Operations), Token Data Tampering, Token Signing-Key Leak, UI Workflow Permission Anomalies, Unauthorized Token Generation, Unrestricted Access to Sensitive Business Flows, Unsafe HTTP Method for Authentication Operations, Unsecured Observability Endpoints, Valid Authentication Baseline, Weak AuthorizationNew categories are added as Perfai’s detection coverage grows, so treat label as an open set of strings rather than a fixed enum.

​
Marking findings fixed, dismissed, or reopened

  • Fix — POST /v1/vulnerabilities/{id}/fix (Mark vulnerability fixed) records a claim pending verification, not a verified result. If the next test still detects the finding, the claim is dropped and it stays open. Perfai reports your claim as fixClaimed, separate from isFixed, which Perfai sets on its own once a finding stops being detected — so fixClaimed is what you asserted, and isFixed is what Perfai observed.
  • Dismiss — POST /v1/vulnerabilities/{id}/dismiss (Dismiss vulnerability) accepts a finding as a known risk so it drops out of your open findings; later tests won’t re-raise it.
  • Reopen — POST /v1/vulnerabilities/{id}/reopen (Reopen vulnerability) undoes a dismissal or a fix claim.
Per-finding detail (Get vulnerability) and security reports (Get reports, Download report) are paid features — the free tier returns 402 Payment Required.

​
Re-mapping with vision runs

A vision run is Perfai’s browser automation: it explores your app like a real user to map the API surface, validate credentials, and discover roles. It runs automatically during onboarding and before scheduled tests, so it is not a required step in the basic register → test → read flow. Call POST /v1/apps/{appId}/vision-agent (Run Vision Agent) only to re-map on demand — after a release that changes your UI or API surface — or to re-validate stored credentials (operation: "validate-login"). API-triggered runs execute browserless in the background; credentials are resolved server-side, so nothing sensitive travels in the request.
Every endpoint mentioned here — with full parameters, request and response schemas, status codes, and a try-it console — lives in the Reference.