Clerk API (unofficial showcase)
POST/agents/tasks

Create agent task

Create an agent task on behalf of a user. The response contains a URL that, when visited, creates a session for the user. The agent_id is stable per agent_name within an instance. The agent_task_id is unique per call.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields
on_behalf_ofobjectrequired
Identifies the user on whose behalf the agent task is created. Exactly one of user_id or identifier must be provided.
permissionsstringrequired
The permissions granted to the agent task. Must be "*" (all permissions).
Allowed:*
agent_namestringrequired
A name identifying the agent. Used to derive a stable agent_id per instance. Logged for audit purposes.
task_descriptionstringrequired
A description of the task being performed. Logged for audit purposes.
redirect_urlstringrequired
The URL the user is redirected to after the agent task is accepted. Must be a valid absolute URL with an `https` scheme in production instances. In development instances, `http` is also permitted. The URL's domain must belong to one of the instance's associated domains (primary or satellite); otherwise the redirect will be rejected when the task ticket is consumed.
session_max_duration_in_secondsintegeroptional
The maximum duration that the session which will be created by the generated agent task should last. By default, the duration of a session created via an agent task lasts 30 minutes.
Default:1800

4 status codes
200Success
objectstringrequired
Allowed:agent_task
agent_idstringrequired
A stable identifier for the agent, unique per agent_name within an instance.
agent_task_idstringrequired
A unique identifier for this agent task.
task_idstringdeprecatedrequired
A unique identifier for this agent task. Deprecated: use agent_task_id instead.
urlstringoptional
The URL that, when visited, creates a session for the user. Only present in the response to a create request.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.