The HTTP API

Everything the SDKs do is a plain HTTPS call, so any language with an HTTP client can use the platform.

Authenticate#

Send your API key (or a user's session token) as a bearer token:

curl https://api.noclick.com/v1/users \
  -H "Authorization: Bearer $NOCLICK_API_KEY"

Act for a user#

Add the NoClick-User header with your id for the user, as it is:

curl -X POST https://api.noclick.com/v1/connections \
  -H "Authorization: Bearer $NOCLICK_API_KEY" \
  -H "NoClick-User: user_42" \
  -H "Content-Type: application/json" \
  -d '{"name": "gmail", "integration": "gmail", "reason": "to send your summaries"}'

In a path, the id is percent-encoded: GET /v1/users/user_42, GET /v1/users/auth0%7C123.

Integrations and operations#

Any key with the tools or credentials:use scope reads the catalog of integrations:

account_free_operation_count is how many of an integration's operations need no account, which is 0 for most. An integration whose kind is model is a model provider (anthropic, openai, ...): it has no operations, and a connection to it is an agent's model_connection, never a tool. subscription says its connect link also offers signing in with the provider's plan. POST /v1/connections/{ref}/token refuses a model provider's connection with 403 permission_denied.

Running an operation takes a key with the credentials:use scope. POST /v1/run takes a ref, "name.operation", the same one an agent's tools take, and resolves it where the call acts:

1. A connection named name runs it, in that connection's account.
2. Else, when an integration is named name and the operation needs no account, it runs on NoClick's key with no connection.
3. Else the call fails. An operation that needs an account answers 400 with invalid_request: create a connection named name. A name that is neither a connection nor an integration answers 404.

curl -X POST https://api.noclick.com/v1/run \
  -H "Authorization: Bearer $NOCLICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "exa.search", "arguments": {"query": "invoice automation"}}'

{"object": "operation_result", "ref": "exa.search", "integration": "exa", "operation": "search", "connection": null, "result": {"results": [...]}}

result is the operation's data, what the service answered. When the service refuses the call, the run answers 424 with upstream_error: the service's own words, and its HTTP status as upstream_status. A service that fails or doesn't answer gives 502 with upstream_error. connection names the connection that ran it, or is null on NoClick's key. On a pending connection, an operation with needs_account: false still runs on NoClick's key, and one that needs an account answers 424 with needs_connection. The same rules resolve the refs in an agent's, a toolkit's and a hosted MCP server's tools. POST /v1/toolkits/call with simulated: {world, scenario} (world a world_ id your code makes once per toolkit) resolves the call the same way, then a simulated world answers it instead of the account (Simulate your own tools). A connection's used_by lists the agents, hosted MCP servers and apps (kind agent, mcp_server, project) holding it.

Agents and harnesses#

An agent's harness is sdk (the default) or a coding harness: claude_code, codex, opencode, hermes or openclaw. POST /v1/agents and PATCH /v1/agents/{id} take harness, model (the harness's own model; the harness's default when omitted, and after a harness change that sends no model) and model_connection, the name of a model provider's connection in the agent's scope. Every harness but sdk needs one; it may still be pending. They take timezone too (an IANA name, null clears it): every turn opens with the date and time there, else in the acting user's timezone (POST /v1/users and PATCH /v1/users/{id} take one), else UTC.

They take repos as well: up to 10 checkouts, each {"connection", "repository", "branch", "path", "push"} with connection a github connection of the agent's scope (it may be pending), repository its owner/name, path the folder under /workspace (the repository's name when omitted) and push a list of branch globs (omitted: read-only). They're stored as sent and the agent carries them as repos (null for a user reading an account agent). Each is cloned at a conversation's first turn through NoClick's git endpoint, which refuses a push to any ref the globs don't name; a turn whose checkout's connection isn't connected fails with 424 needs_connection (with its connect_url for a caller in the connection's scope). A repo_id entry (a NoClick repo) is in invite-only beta: without access, it answers 400.

A harness's model list comes from its providers' own catalogs, thousands of models on sdk, so it's searched rather than listed with the harness; a search after a few quiet minutes reads them afresh and can take several seconds.

A turn on a coding harness is an agent.message operation like any other, whose step says where it is while it runs: delivering while its sandbox starts and takes the message, then working. It's null on sdk and once the operation ends. A pending model connection fails the turn with 424 needs_connection, a revoked one with 424 credential_disconnected, and a key the provider refuses carries the provider's own words.

{"object": "operation", "id": "3b9e...", "kind": "agent.message", "status": "running", "step": "working", "result": null}

A wake-up gives one of an agent's conversations, the NoClick-User header's thread, a turn later; it takes the agents scope. See Wake it up later.

A channel's conversation (channel:<id>) takes turns only from the channel, so POST /v1/agents/{id}/messages and POST /v1/agents/{id}/wakeups refuse it with 400 invalid_request (field: "conversation"), and A2A and the AI API refuse it in their own error shapes. A delivered wake-up's operation_id is the agent.message operation its turn runs as, and woken_by says what woke it: {"at"} for a time, {"operation_id", "kind", "status", "result" | "error"} for an operation, {"update"} for a child's update. NoClick's own wake-ups have source update, answer (a connect link the agent asked for is done) or approval (a held call was decided).

Spawning, jobs and asking take the agents scope. See Coordinators and sub-agents.

Each agent carries job_id, the task spawn started it with. A job's view adds started_by (its parent, or the agent that sent the message), conversation (the worker's: a child's is task), parent_conversation (the one its updates wake, or null), updates and latest_update.

In tools, "agents" gives an agent the tools to spawn, message, ask, check, list and cancel other agents in its own conversations, and "agents.spawn" and its siblings give one each; any other agents.<name> answers 400, and a connection can't be named agents. A message it sends is an agent.message job, so its reply is the job's done update. A job_update has id, job_id, agent_id, kind (done, blocked, before, every or message), text, tool, arguments, status (the job's then), result, error, waiting_on ({"kind": "connection" | "approval", "url", "operation_id"}), wakeup_id and created_at.

A test run takes the agents scope too:

An agent's memory takes the agents scope. Each call acts on one layer: for an account agent the account's (no NoClick-User) or the acting user's; a user's own agent has only its user's. user_id (none or a user's id, from a key acting for the whole account) names the layer instead of the header, without acting for the user, so a suspended user's memory still reads.

Streaming, watching and sharing take the agents scope. See Sharing and streaming.

Both streams send a : keepalive comment every 15 seconds. A turn's result carries model_usage (input_tokens, output_tokens, cached_tokens, usd) for an agent with a model_connection, else null; so does each conversation in GET /v1/agents/{id}/conversations. Only the agent's owner shares it: a user acting on an account agent gets 403.

Each agent carries ttl_s (the time to live it was made with), status (working while a turn is queued, running or held, idle, or expired past its ttl_s), last_active_at, running_turns and child_count; with NoClick-User set, an account agent's last four are null, and its activity filters never match it. GET /v1/agents lists expired agents for the 30 days they're kept, filters by status, active_since, parent_id, temporary (true or false) and harness, and sorts by order (created, the default, or last_active). An expired agent answers a message or a PATCH with 410 expired; DELETE removes it.

Triggers and channel subscriptions#

An agent's triggers and its pause switch take the agents scope, a channel's subscriptions and schedules the channels scope, and the events catalog tools or credentials:use. See Triggers and Subscribe a channel to events.

POST /v1/agents takes triggers, a list of the same definitions, checked before anything is made, and POST /v1/channels takes a channel's schedules the same way; PATCH /v1/channels/{id} changes an open channel's mode, max_agent_turns, max_mention_hops and budget_usd (null lifts the budget). An agent_trigger has id, agent_id, channel_id, kind, spec (its definition without kind), status (active, paused while its agent is, or error, with error saying why it hears nothing), url (a webhook's), next_run (a schedule's), last_fired_at and created_at. An agent has paused and trigger_kinds (null for a user reading an account agent) and timezone; a subscription has channel_id, source, wake, filters, status, error, url and last_event_at.

A POST to a webhook's url answers 202 with {"object": "trigger_delivery", "status", "operation_id", "conversation"} for an agent (status is pending while its conversation answers an earlier delivery, failed with an error when the account can't pay), and {"status": "posted", "message_id"} for a channel (200 filtered when its filters don't match). A NoClick-Conversation header picks an agent's conversation. The turn is an agent.message operation whose input has the event and the trigger (id, kind, title). A message a subscription posts has author.type app, its subscription_id and the event as it arrived.

Webhooks and events#

These take the webhooks scope, and reading a secret webhooks:reveal, which * doesn't grant. An endpoint lives where the call acts: your account's receives every event, a user's (NoClick-User) only that user's. See Webhooks and events.

An event has id, type, user_id, created_at and data. A webhook_delivery has id, webhook_id, event_id, event_type, status (pending, retrying, succeeded or failed), attempts, response_status, response_body (its first 4 KB), request_body, duration_ms, error, next_retry_at and created_at. A delivery is a POST of the event's JSON with a NoClick-Signature: t=<unix seconds>,v1=<hex> header, where the hex is HMAC-SHA256 of <t>.<body> keyed with the endpoint's secret (two v1 values while a rotated secret's grace runs). A 2xx within 10 seconds succeeds; anything else, a redirect included, is retried after a minute, five minutes, half an hour, two hours, five hours, then every 12 hours, for 3 days.

Workspaces#

Workspaces take the channels scope and live where the call acts: your account, or the user NoClick-User names. See Workspaces.

A workspace has id, name, logo_url, user_id, status, budget_usd_per_month, spent_usd (this UTC month), channel_count (its open channels), members and created_at; a workspace_member has id, type (agent or user), agent_id, user_id and name. POST /v1/channels takes workspace_id (its agent and user members must be the workspace's, 400 otherwise, and its name unique among the workspace's open channels, 409 with existing_id); a workspace channel's members and a post's as may be {"user_id": "<your id>"}; GET /v1/channels filters by workspace_id and name; a channel has workspace_id. A workspace subscription's webhook answers {"status": "posted", "message_ids"}, one message per open channel it posts in.

Volumes and buckets#

Volumes take the volumes scope and buckets storage. Each lives where the call acts: your account, or the user NoClick-User names. A user reaches its own volumes and your account's, and its own buckets. See Volumes and Storage.

A volume_entry has path (from the volume's root), type (file or directory), size and updated_at; a bucket_object has key, size, content_type, etag, metadata, updated_at and folder. A public bucket serves each file at public_base_url + key, which redirects to a short-lived signed link. POST /v1/sandboxes, POST /v1/agents and PATCH /v1/agents/{id} take volumes ({"/data": "<volume id or name>"}), and both carry it. A bucket is one of an agent's tools as bucket:<id> (all five operations) or bucket:<id>.<operation> (objects, head, put, signed_url, remove), bound as {"tool": "bucket:<id>.put", "bind": {"prefix": "users/{{user.id}}/"}}.

An agent's per-conversation files take the agents scope, in the caller's user's thread (else the agent's own user's, else your account's):

Secrets, dicts and queues#

Each takes its own scope (secrets, dicts, queues) and lives where the call acts: your account, or the user NoClick-User names, its name (1 to 64 letters, digits and . _ -) unique there; a taken name is 409 with existing_id. A user's call reads its own dicts and queues, and its own secrets and your account's. Dicts and queues keep their data in us-east (region takes no other yet: another, or a default region elsewhere, is 400 naming the regions that do). See Secrets, Dicts and Queues.

A queue_message has id, queue_id, body, status (waiting, delayed, in_flight or dead), attempts (deliveries, this one included), enqueued_at, visible_at (while delayed), lease_expires_at, last_error, dead_lettered_at, and on a take its lease_id. Waiting messages and dead letters are kept 14 days. POST /v1/sandboxes, POST /v1/agents and PATCH /v1/agents/{id} take secret_ids (their keys in the environment, a later one's winning; an agent's never a model provider's key), and both carry it. POST /v1/dicts/{id}/export and POST /v1/queues/{id}/export start a dict.export or queue.export operation (see Export).

Regions#

Where a resource runs or keeps its data, in NoClick's own names. See Regions.

POST /v1/sandboxes and POST /v1/agents take region, and a sandbox and an agent carry it (null: wherever NoClick had capacity). A missing region takes a child agent's parent's, else your account's default. An agent's region never changes: PATCH /v1/agents/{id} with another answers 409 conflict with region. Your account's default is set in the console.

Hosted MCP servers#

A hosted MCP server serves a toolkit's tools at one URL; these take the mcp_servers scope and live where the call acts: your account, or the user NoClick-User names, whose connections its calls act in. See Hosted MCP servers.

An mcp_server has id, name, url, tools (as sent), tool_count (what it serves right now: an entry whose connection isn't connected serves nothing), user_id, created_at and last_client_at. An mcp_client has name and version as the client gave them, first_seen_at, last_seen_at and tool_count (what it saw when it last listed). The url speaks MCP over Streamable HTTP (stateless, JSON replies) and needs no key: initialize answers with an Mcp-Session-Id the client sends back, tools/list serves the tools, and tools/call runs one it serves as a toolkit call, as the key that made the server, recorded as a tool call with source mcp_server and its mcp_server_id. GET /v1/tool_calls?source=mcp_server lists them.

Inboxes, phone numbers and brand#

These take the inbox, phone and brand scopes. See Inboxes, Phone numbers and Brand.

A number has source (bought or connected), country, type, connection (a connected number's), agent_id, transfer_to, callers, record_calls and monthly_usd (null for a connected number, which its provider bills). A call has direction, from, to, status (calling, then completed, not_connected, refused, failed or lost), user_id (the user it ran as), transcript, transfer (to, status, seconds) and recording_url (a signed link valid for an hour, when the number records its calls).

oauth_redirect_urls has, for every provider you can bring an OAuth app for, the redirect URI to register with it. An account key changes the brand; a user's key only reads it.

AI models#

/v1/ai is OpenAI-compatible: point an OpenAI client at https://api.noclick.com/v1/ai with your key. A model call takes the ai scope; model: "agent:<name>" (or agent:<id>) talks to one of your agents and takes agents. See AI models.

Every answer carries cost_usd. Errors on these routes use OpenAI's shape, {"error": {"message", "type", "param", "code"}}, with NoClick's type in code and next_step beside it. A request that doesn't stream must answer within 90 seconds or fails with 504 request_timeout (sent with x-should-retry: false); a stream starts at once and sends a : keepalive comment every 15 seconds while it waits.

Workflows#

Workflows, built from a description by NoClick's builder and run from your code; they take the workflows scope. See Workflows.

A public endpoint also takes a publishable key that lists it.

Objects and lists#

Objects are JSON with an object type and an id:

{"object": "user", "id": "user_42", "name": "Ana Lima", "status": "active"}

Lists wrap them with a cursor. Pass next_cursor back as cursor for the next page; null means you've reached the end:

{"object": "list", "data": [...], "next_cursor": "eyJ0IjoiMjAyNi0..."}

Errors#

A failed request answers with its HTTP status and an error object:

{
  "error": {
    "type": "needs_connection",
    "message": "The 'gmail' connection has no Gmail account connected for this user yet.",
    "next_step": "Send the user connect_url; retry once the connect operation succeeds.",
    "connection": "gmail",
    "integration": "gmail",
    "connect_url": "https://noclick.com/credential/provide/...",
    "operation_id": "3b9e..."
  }
}

type is stable; the Error reference lists each one with its status. A path no route serves answers 404 not_found, and a method its route doesn't take 405 invalid_request (with Allow). When a key's request rate is over its limit, the 429 carries Retry-After; a daily send cap says when it frees in retry_after instead.

Every response carries an X-Request-Id. Quote it when you contact support.

Make writes safe to retry#

Send an Idempotency-Key header with every POST. Repeating a request with the same key and the same body returns the first response instead of running again, for 24 hours. A replayed response carries Idempotent-Replayed: true. A request refused with a 4xx isn't remembered, so a repeat runs again, and a repeat that arrives while the first request is still running gets a 409: send it again shortly.

Long-running work#

Work that waits returns an operation object:

{"object": "operation", "id": "3b9e...", "kind": "credential.connect", "status": "awaiting_human", "result": null}

Long-poll it until it's final. Each call waits up to the timeout_s you pass (up to about a minute) and returns the operation as it stands:

curl "https://api.noclick.com/v1/operations/3b9e.../wait?timeout_s=50" \
  -H "Authorization: Bearer $NOCLICK_API_KEY"

GET /v1/operations/{id} reads it without waiting, and POST /v1/operations/{id}/cancel cancels it.

From a browser#

The API answers cross-origin requests from any origin. Use a session token or a publishable key, never your secret key, and send it as a bearer; the API never reads cookies.

Keys and the CLI#

A publishable key (nk_pub_) is made on the console's API keys page (POST /v1/keys with type: "publishable", public_endpoints as {kind, id}, per_visitor_limit_per_minute and allowed_origins; GET /v1/public_endpoints lists what may go in it, and PATCH /v1/keys/{id} changes the three): it calls only the public endpoints it lists, such as a shared agent's chat, from those origins, within its limit per visitor, and every other route answers it 403. A key's view says its type (secret or publishable) and shows a publishable key in full, as publishable_key. The CLI signs in with routes of its own; the first two need no key:

Databases, repos, apps, domains and browsers#

These follow every convention above. A resource lives at /v1/<plural> and /v1/<plural>/{id}; GET /v1/<plural>?name= finds one by name, which is unique for its user; user_id on a list reads across users (all, none, or one user's id), while the NoClick-User header acts as one. Actions are POST to /{id}/<verb>, and every write takes an Idempotency-Key.

Long work answers 202 with an operation of its own kind (project.deploy, domain.buy, database.restore, workflow.run, user.export, ...), which you wait on as above; /wait returns its result once it has succeeded. A purchase takes a ceiling (max_price_usd, max_monthly_usd) and answers 402 price_exceeded above it, a call your account can't pay for answers 402 payment_required, and a purchase your policy holds waits in awaiting_human until a person approves it. Every purchase is charged to your account; NoClick never bills your users. Secret values are write-only, and tokens and credentials come back short-lived.

Databases#

In an agent's tools, a database is database:<id> (query, execute and schema), or database:<id>.query for one operation.

Repos#

Apps#

An app is a project: a repo deployed to a URL, with what the running app needs.

A deployment's credential (NOCLICK_DEPLOYMENT_TOKEN in its environment) is a bearer that acts as a key of the app's user, attributed to the app: GET /v1/projects/current reads the app, its bindings resolve, and every other route a key of that user reaches answers it, except: what the gate keeps for a person (403 permission_denied: keys, grants, sessions, caps and budgets, policy, approvals' answers, raw tokens, secrets' values, accepting terms), what files a person's details with a carrier (documents, a port, a texting registration), turning on a domain's auto-renew, and the areas beyond the app (quotes, humans, users, tool_calls, approvals, trash, policy). A purchase (POST /v1/phone_numbers, POST /v1/domains) charges what it costs now within what's left of the app's budget (402 spend_cap_exceeded with remaining_usd, else), is the app's, renews within its budget, and one in a person's name answers 402 approval_required until they approve it. Calls, texts, automations, hosted MCP servers, channels, machines and cards count toward the app's budget and wait on it; of workflows and workspaces it reaches only what its code made. It reads its own user's events, webhooks, usage and the attachments its code uploaded, and its own requests and operations, never changing them. It acts for the app's user alone: NoClick-User, and a user_id naming anyone else, answer 403. On a resource its own code didn't make it reads and uses (its data, a message, a run) but never changes or deletes it (403), and on one bound to the app it may also clear its data; another app, and what another app's code made (by id, or named in a body), answer 403 and 404; an operation it didn't start, 404. POST /v1/agents/{id}/messages (and /ask, /a2a) starts turns in the app's own threads, a conversation it sends being kept as app:<app id>:<key> (from a preview, app-preview:<app id>:<key>, its turn answered by a simulated world), and is refused (403) for an agent holding the noclick tool; POST /v1/agents and PATCH refuse giving an agent the noclick or agents tools, a person other than the owner, or a platform trigger. Once the app's budget or its user's cap is used up, a paid call answers 402 spend_cap_exceeded (scope project or user), and once your balance is, 402 payment_required, each naming the app in project and project_id. GET /v1/usage?group_by=project splits spend by app, and GET /v1/usage/limits adds projects.

App services#

Payments aren't switched on yet: until they are, POST /v1/projects/{id}/payments answers 409 not_available.

Domains#

Browsers#

Cards#

These take the cards scope. See Cards.

POST /v1/agents and PATCH /v1/agents/{id} take card_id, the card the agent holds and pays with (null takes it back; giving one takes the cards scope), and an agent carries it.

Cards are in invite-only beta. Without access, GET /v1/cards/program, GET /v1/cards/funding, POST /v1/cards and an agent's card_id answer 409 not_available, with no program_status; the other routes answer as for an account with no cards, and merchant_categories lists the categories. With access, issuing a card or reading funding before your company's program is active answers not_available with program_status and requirements_due.

Invite-only beta routes#

They follow the same conventions.

Phone numbers#

Porting a number in, beside the phone number routes that work today. A ported number's source is ported.

Machines#

Every create of a resource that holds data or hosts code (databases, apps, machines; buckets, dicts and queues already do) takes region, fixed for its life. An agent takes machine_id to run on a machine.

Agents#

Beside the agent routes that work today: a connection from another scope, another user's or the account's, is connection:<id> (or connection:<id>.<operation>), accepted only on a key acting for the whole account; POST /v1/toolkits/call then takes the toolkit's tools too, so the tool's name resolves to that connection.

Export#

An export is an operation: read it (and its bundle, once it succeeded) with GET /v1/operations/{id} or /wait. Its result is an export: url (the zip, valid until expires_at), size_bytes, contents (each {kind, name, detail}) and remaining_dependencies. A second export of the same user or resource while one runs answers 409 with its operation_id.