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.
curl --request POST \
--url https://api.perfai.ai/v1/apps/{appId}/vision-agent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"operation": "map"
}
'{
"taskId": "<string>",
"appId": "<string>",
"operation": "<string>",
"state": "QUEUED",
"reason": "needs_login",
"message": "We hit a snag — we're on it. Your results so far are saved.",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"statusUrl": "<string>"
}{
"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
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.
Path Parameters
MongoDB ObjectId of the app (from GET /apps or POST /apps).
Body
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.
map, validate-login, discover-roles, verify-rbac Response
Vision run accepted.
Vision operation (internally created runs may surface their raw task type).
Same vocabulary as TaskState. Never FAILED.
QUEUED, RUNNING, NEEDS_INPUT, COMPLETED, COMPLETED_PARTIAL, INTERRUPTED, CANCELLED 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.
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 One sentence for the user — the same wording the console shows for this state.
"We hit a snag — we're on it. Your results so far are saved."
curl --request POST \
--url https://api.perfai.ai/v1/apps/{appId}/vision-agent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"operation": "map"
}
'{
"taskId": "<string>",
"appId": "<string>",
"operation": "<string>",
"state": "QUEUED",
"reason": "needs_login",
"message": "We hit a snag — we're on it. Your results so far are saved.",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"statusUrl": "<string>"
}{
"type": "<string>",
"title": "<string>"
}{
"type": "<string>",
"title": "<string>"
}{
"type": "<string>",
"title": "<string>"
}{
"type": "<string>",
"title": "<string>"
}{
"type": "<string>",
"title": "<string>"
}{
"type": "<string>",
"title": "<string>"
}