> ## 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. # Run Vision Agent > Asynchronously launches a vision (browser-automation) run for the app. Partner-triggered runs always execute browserless on the background browser pool — there is no mode parameter. Credentials are resolved server-side from the app's stored authentication; none travel in the request. Rate limit 5 requests / 60 s per IP. ## OpenAPI ````yaml /api-reference/openapi.yaml post /apps/{appId}/vision-agent 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/{appId}/vision-agent: post: tags: - Vision Agent summary: Run Vision Agent description: > Asynchronously launches a vision (browser-automation) run for the app. Partner-triggered runs always execute browserless on the background browser pool — there is no mode parameter. Credentials are resolved server-side from the app's stored authentication; none travel in the request. Rate limit 5 requests / 60 s per IP. operationId: runVisionAgent parameters: - $ref: '#/components/parameters/AppId' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/TriggerVisionRun' examples: map: summary: Re-map the app (default) value: operation: map validateLogin: summary: Verify stored credentials still work value: operation: validate-login responses: '202': description: Vision run accepted. headers: Location: description: Status URL for the vision run. schema: type: string content: application/json: schema: $ref: '#/components/schemas/VisionRunResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- Vision run already active (vision-run-already-active, includes activeVisionRunId). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': $ref: '#/components/responses/RateLimited' '500': description: >- vision-task-create-failed — the run was not created; retry the request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' components: parameters: AppId: name: appId in: path required: true schema: type: string description: MongoDB ObjectId of the app (from GET /apps or POST /apps). schemas: TriggerVisionRun: type: object additionalProperties: false properties: operation: type: string enum: - map - validate-login - discover-roles - verify-rbac default: map description: > map — explore the app and generate/refresh the API spec; validate-login — verify stored credentials still work; discover-roles — discover RBAC roles; verify-rbac — re-verify role capabilities. VisionRunResponse: type: object properties: taskId: type: string appId: type: string operation: type: string description: >- Vision operation (internally created runs may surface their raw task type). state: $ref: '#/components/schemas/VisionRunState' createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time statusUrl: type: string 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 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' NotFound: description: Resource not found or belongs to a different tenant. 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. ````