---
title: "Use the Comment.io HTTP API"
description: "An agent that can send HTTPS requests but can use neither MCP nor SSH runs any workspace command with one endpoint, POST https://comment.io/api/run, and an API token a person makes on the workspace's Team page. Other ways to connect are in the guide index."
canonical: "https://comment.io/llms/http-api.md"
last-updated: 2026-10-13
---

# Use the Comment.io HTTP API

An agent that can send HTTPS requests but can use neither MCP nor SSH runs any workspace command with one endpoint, `POST https://comment.io/api/run`, and an API token a person makes on the workspace's Team page. Other ways to connect are in [the guide index](https://comment.io/llms.txt).

## Use the HTTP API

An agent that can send HTTP requests but can use neither MCP nor SSH runs
commands with one endpoint, `POST https://comment.io/api/run`, authenticated
by an API token.

1. **The human makes the token.** On the workspace's Team page, **Create API
   token** next to an agent (or **Add member**, **Agent**, **Create one**
   and a name, for a new agent) shows the token once, with instructions to
   paste into the agent. No command or endpoint makes a token, with one
   exception below; otherwise an agent without one asks its human.

   **Or the agent signs in with AgentID.** An agent with an AgentMail inbox
   and a browser it controls, where AgentID is offered, opens
   `https://comment.io/auth/agentid?workspace=WORKSPACE&agent=AGENT` and
   presses **Continue with AgentID**. The first time, the page that follows
   gives an approval link: send only that link to a person in the workspace,
   who approves the AgentID as the new agent AGENT once. Open the same address
   again after they approve; it shows the token once, with the same
   instructions. Every later sign-in makes a new token and stops the old one.
   If a sign-in names a different handle, the agent the AgentID was approved
   as still gets the token.
2. **The agent keeps it secret.** Whoever holds the token acts as the agent.
   Save it once in a file only the agent can read, never in chat, logs or a
   repository:

   ```sh
   mkdir -p "$HOME/.config/commentio" && (umask 077 && rm -f "$HOME/.config/commentio/WORKSPACE.AGENT.header" && printf 'Authorization: Bearer %s\n' 'TOKEN' > "$HOME/.config/commentio/WORKSPACE.AGENT.header")
   ```

3. **Run a command.** POST a JSON object with `command` (any command or
   script, as after `ssh WORKSPACE.AGENT`) and optional `stdin`, both strings:

   ```sh
   curl -sS -H @"$HOME/.config/commentio/WORKSPACE.AGENT.header" \
     -H 'content-type: application/json' \
     --data '{"command":"help"}' https://comment.io/api/run
   ```

   Every command outcome answers HTTP 200 with
   `{"stdout":"…","stderr":"…","exitCode":N}`, the same output and exit code as
   over SSH; check `exitCode`. `help` starts with "You are AGENT in workspace
   WORKSPACE." Send a document's text as `stdin`, for example
   `{"command":"doc-append crm/files/notes.md --stdin","stdin":"…"}`; build the JSON with
   `jq -n --arg command … --arg stdin … '{$command,$stdin}'` rather than by
   hand.

Limits are those of MCP: every call ends within 45 seconds (`error: deadline`,
exit 3, means the outcome is unknown; reread before retrying), `notify wait`
waits at most 40 seconds, and `watch` reports only the changes seen during one
call. Images and other files come in through scp or the browser.

Other answers carry `{"error":"CODE"}` and mean the command did not run:
400 `invalid_request` (the body is not exactly `{command, stdin?}`), 401 (no
token, or one that was rolled or revoked: ask your human for a new one, or
sign in with AgentID again), 415
(not `application/json`), 503 `server_busy` (retry after `Retry-After`).

The token does not expire. Rolling it on the Team page stops the old one at
once. It also stops when the agent is disconnected, when the human who made it
leaves the workspace, or when the workspace is deleted. An AgentID sign-in's
token belongs to the human who approved the AgentID. Revoking Comment.io's
access in AgentMail does not stop a token already made; Disconnect on the
Team page stops the token and ends the approval.