Anything API

Build and run web automations from a single API call

AI agent instructions

STOP. Do not read past this section until you have read and followed /quickstart.md.

Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.

Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live observe() call, CLI notte page observe output, or generated workflow code. Guessed browser targets fail on real pages.

Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with notte sessions workflow-code before using SDK docs or SDK code.

SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.

The Anything API lets you describe a task in plain English, and Notte will build, deploy, and run a web automation function for you — all through a single HTTP request. The response streams the agent’s progress as an AI SDK UI message stream, or you can detach and let the run continue in the background.

Try it now

Open the Anything API web app.

Get your API key

Create an account on the Console to get started.

Quick start

curl -N -X POST https://anything.notte.cc/api/anything/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -d '{"query": "fetch the top 3 hacker news posts"}'

The API streams the agent’s work back as an AI SDK UI message stream. The x-thread-id response header identifies the thread handling your run, so you can send follow-up turns into the same thread later.

Request

query · string · required

A natural-language description of the task you want automated.

thread_id · string (UUID)

Send a follow-up turn into an existing thread. The sandbox state and conversation carry over. Omit to start a new thread.

detach · boolean · default: "false"

Start the run and return immediately instead of streaming. See Detached mode.

model · string

Optional model override for the agent.

reasoningEffort · string

Optional reasoning effort override for the agent.

version · string · default: "v2"

API contract version. "v2" is the only supported value and the default, so you can omit this field. Explicit "v1" returns 400 — see Migrating from v1.

POST /api/anything/start

{
  "query": "fetch the top 3 hacker news posts"
}

Headers

Header	Required	Description
Authorization	Yes	Bearer <NOTTE_API_KEY>
Content-Type	Yes	application/json

Response

Streamed (default)

By default, the response is an AI SDK UI message stream — the same format the Vercel AI SDK’s useChat hook consumes, so you can point a chat UI straight at the endpoint or read the stream yourself.

Response headers

Header	Description
x-thread-id	ID of the thread handling this run. Use it as thread_id in follow-up requests.
x-vercel-ai-ui-message-stream	v1 — the AI SDK’s stream-format version. Unrelated to the retired v1 backend.

Detached mode

Pass detach: true to start the run and return immediately with 202 Accepted:

cURL

curl -X POST https://anything.notte.cc/api/anything/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -d '{"query": "fetch the top 3 hacker news posts", "detach": true}'

The response body contains:

Field	Description
thread_id	ID of the thread handling the run (also sent as the x-thread-id header).
url	Link to the thread page in the app, where you can follow the run.
status	"started"

Follow-up turns

Pass the thread_id from a previous response to continue the conversation in the same thread. The sandbox state and conversation history carry over, so the agent can build on its earlier work:

curl -N -X POST https://anything.notte.cc/api/anything/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -d '{
    "query": "now also include each post'\''s comment count",
    "thread_id": "820a7cff-613b-4529-9ba4-52c7a6777713"
  }'

Follow-up turns work in both streamed and detached mode.

Consuming the stream

Python

consume_stream.py

import json
import os

import requests

NOTTE_API_KEY = os.environ["NOTTE_API_KEY"]

response = requests.post(
    "https://anything.notte.cc/api/anything/start",
    headers={
        "Authorization": f"Bearer {NOTTE_API_KEY}",
        "Content-Type": "application/json",
    },
    json={"query": "fetch the top 3 hacker news posts"},
    stream=True,
    timeout=(10, 600),
)
response.raise_for_status()

# The thread ID lets you send follow-up turns later
thread_id = response.headers["x-thread-id"]
print("Thread ID:", thread_id)

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode("utf-8")
    if not decoded.startswith("data: "):
        continue
    payload = decoded[len("data: ") :]
    if payload == "[DONE]":
        break
    chunk = json.loads(payload)
    print(chunk.get("type"), chunk)

TypeScript

const response = await fetch("https://anything.notte.cc/api/anything/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${NOTTE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "fetch the top 3 hacker news posts" }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
if (!response.body) {
  throw new Error("ReadableStream not available");
}

// The thread ID lets you send follow-up turns later
const threadId = response.headers.get("x-thread-id");
console.log("Thread ID:", threadId);

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop()!;

  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const payload = line.slice("data: ".length);
    if (payload === "[DONE]") break;
    const chunk = JSON.parse(payload);
    console.log(chunk.type, chunk);
  }
}

If you are building a chat interface, you can skip the manual parsing: the stream is directly compatible with the AI SDK’s useChat hook.

Re-running a created function

When a run creates a reusable Notte Function, you can run it again via the Notte CLI or SDK:

CLI

notte functions run \
  --function-id d3c31289-f28b-49bd-a340-95e071cfef7e \
  --vars '{"count": "3"}' \
  -o json

Migrating from v1

The v1 backend is retired. Requests with version: "v1" return 400 {"error": "unsupported_version"} with a retirement message.

If you were calling the v1 API:

• Omit version (or send "v2"). It now defaults to "v2".
• Responses are an AI SDK UI message stream instead of the v1 SSE event feed. The v1 event types (status, thinking_delta, done, …) no longer exist.
• Follow-ups use thread_id. The v1 concepts resume_strategy, snapshot semantics, and claude_code_session_id are gone: pass the thread_id from the x-thread-id response header to continue a thread.
• The x-vercel-ai-ui-message-stream: v1 response header refers to the AI SDK’s own stream-format version, not the retired v1 backend.

Error handling

Status	Meaning
400	Missing query field, invalid JSON, or version: "v1" (unsupported_version)
401	Missing or invalid API key