NotchVerifiedFeatured

List the Notch workspaces the user belongs to. New ad sessions are created and billed in the active workspace (marked isActive). Use select_workspace to switch.

Switch the active Notch workspace — where new ad sessions are created and billed. Pass a workspaceId from list_workspaces.

List recent ad sessions in the active workspace, most recently active first. Any of these can be resumed with send_message or get_session_updates.

Create a new Notch ad session from a plain-language brief and start the agent working. Returns the sessionId to poll with get_session_updates, plus the workspace and credit balance to relay to the user. Fails fast (before any work) if the workspace can't afford the minimum billable render. If the account has several workspaces and hasn't picked one for this connection, no ad is created and the result asks which workspace to use — relay that question, then call again with workspaceId, or useActiveWorkspace when they explicitly confirm the current one.

Long-poll for what's new in an ad session: status, progress lines, milestone media, agent questions, and final deliverables. The server tracks what it already sent you — each call returns only new items, and always carries the current status plus any question the agent is waiting on. Holds server-side and returns as soon as there is something to report — call it again immediately while status is "working".

Continue an ad session's conversation: answer the agent's questions, request edits, or submit an intake form. After sending, poll get_session_updates for the agent's response.

Stop the agent's in-flight work on an ad session — call this when the user asks to stop, cancel, or abandon the ad. The session itself is kept: a later send_message resumes it, and work the agent already finished stays done.

Open an upload box so the user can put one of their local files (a product photo, a reference image or video) into the ad. Use this whenever the user has a file on their device and this client can show interactive UI: they drop the file in the box, it uploads straight to Notch, and its URL comes back to you to pass in attachments. Never ask the user to attach a local file to the chat instead — chat attachments can't be read; the box is the way in. Wait for the user to finish the upload before using the returned URL.

Get a file into an ad when you hold the bytes yourself, returning a URL to pass in attachments. In a code or terminal environment, call it for a presigned URL and PUT the bytes there. For a very small file you may instead pass its base64 contents as fileData to store it in one step. When the file is on the user's device in a chat client, use upload_file instead so they upload it through a box.