POST
/
agents
/
start
curl
curl -X POST "https://api.notte.cc/agents/start" \
-H "Authorization: Bearer $NOTTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "task",
"url": null,
"response_format": null,
"session_offset": null,
"reasoning_model": null,
"use_vision": true,
"max_steps": 20,
"vault_id": null,
"persona_id": null,
"notifier_config": null,
"session_id": "session_id"
}'
{
  "agent_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "session_id": "<string>",
  "status": "active",
  "closed_at": "2023-11-07T05:31:56Z",
  "saved": false,
  "credit_usage": 123
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
x-notte-request-origin
string | null
​
x-notte-sdk-version
string | null

Body

application/json
​
task
string
required

The task that the agent should perform

​
session_id
string
required

The ID of the session to run the agent on

​
url
string | null

The URL that the agent should start on (optional)

​
response_format
any

The response format to use for the agent answer. You can use a Pydantic model or a JSON Schema dict (cf. https://docs.pydantic.dev/latest/concepts/json_schema/#generating-json-schema.)

​
session_offset
integer | null

[Experimental] The step from which the agent should gather information from in the session. If none, fresh memory

​
reasoning_model

The reasoning model to use

Available options:
openai/gpt-4o,
gemini/gemini-2.0-flash,
vertex_ai/gemini-2.0-flash,
vertex_ai/gemini-2.5-flash,
openrouter/google/gemma-3-27b-it,
cerebras/llama-3.3-70b,
groq/llama-3.3-70b-versatile,
perplexity/sonar-pro,
deepseek/deepseek-r1,
together_ai/meta-llama/Llama-3.3-70B-Instruct-Turbo,
anthropic/claude-3-5-sonnet-20240620
​
use_vision
boolean
default:true

Whether to use vision for the agent. Not all reasoning models support vision.

​
max_steps
integer
default:20

The maximum number of steps the agent should take

Required range: 1 <= x <= 50
​
vault_id
string | null

The vault to use for the agent

​
persona_id
string | null

The persona to use for the agent

​
notifier_config
object | null

Config used for the notifier

Response

Successful Response

​
agent_id
string
required

The ID of the agent

​
created_at
string<date-time>
required

The creation time of the agent

​
session_id
string
required

The ID of the session

​
status
enum<string>
required

The status of the agent (active or closed)

Available options:
active,
closed
​
closed_at
string<date-time> | null

The closing time of the agent

​
saved
boolean
default:false

Whether the agent is saved as a workflow

​
credit_usage
number | null

Credit usage for the agent. None if the agent is still running