API

The n8v API lets other systems act on n8v the way you do: start a chat on a repository, branch and model of your choosing, and send a message into a chat that already exists. Every call is recorded in an audit log, and the keys that make the calls can be created and revoked at any time.

In the API, a chat is what the app calls a task. The id it returns is the one in the task's address, https://n8v.online/task/<id>.

Quickstart

curl -sS --fail-with-body --retry 3 --retry-max-time 120 \
  -X POST https://n8v.online/api/v1/chats \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{
    "repo": "owner/name",
    "message": "Fix the failing build and open a pull request"
  }'

{
  "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "repo": "owner/name",
  "baseBranch": "main",
  "branch": null,
  "model": "sonnet-5"
}

curl -sS --fail-with-body --retry 3 --retry-max-time 120 \
  -X POST https://n8v.online/api/v1/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{
    "message": "Also add a regression test"
  }'

{
  "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "queued": false
}

The Settings page shows the same examples with your repository filled in, as cURL, JavaScript and a GitHub Actions step.

Conventions

• Base URL: https://n8v.online/api/v1. Send and receive JSON.
• Authentication: Authorization: Bearer n8v_sk_.... Call the API from a server or CI job, never from a browser: the API sends no CORS headers, and a key in a web page is a leaked key.
• Request id: every response carries X-Request-Id. For authenticated calls it is also in the audit log. Quote it when you ask for help.
• Errors: {"error": {"code": "...", "message": "...", "param": "..."}}. Branch on code, never on the message. param names the field at fault when there is one; hint says what to do next, when there is something.
• Caching: responses are never cached.
• Methods: each endpoint serves the methods listed below. Any other standard method answers 405 with an Allow header naming the ones it serves.

Start a chat

POST /api/v1/chats, needs the chats:create scope.

Answers 202 with id, url, repo (as GitHub spells it), baseBranch, branch, the model that will be used and peers. branch is the branch the agent works on when it is known now: the one you named, or branch with newBranch: false. It is null while a generated name is still to be chosen, as the agent starts. The agent runs with the same permissions as a chat you start yourself in the app, and the chat appears in your task list.

Name the new branch

Send newBranchName to choose the new branch's name instead of a generated one:

curl -sS --fail-with-body -X POST https://n8v.online/api/v1/chats \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{
    "repo": "owner/name",
    "message": "Fix the login redirect",
    "newBranchName": "fix/login-redirect",
    "ifBranchExists": "suffix"
  }'

{
  "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "repo": "owner/name",
  "baseBranch": "main",
  "branch": "fix/login-redirect",
  "model": "sonnet-5"
}

• Created right away. n8v creates the branch on GitHub from branch (or the default branch) when the chat is created, so branch in the answer is final and no other chat can take the name.
• Exactly as given. The branch name prefix in Settings applies to generated names only.
• Git's rules. No spaces, quotes, .., @{ or any of ~ ^ : ? * [ \, not starting with - or /, not ending with /, . or .lock, at most 255 characters, and not a full ref (refs/heads/...). Otherwise 400 invalid_request with param: "newBranchName", before anything is created.
• Taken names. By default a name that exists, or that has branches below it (fix when fix/a exists), answers 409 branch_exists. With "ifBranchExists": "suffix" the chat gets the first free name-2, name-3, and branch in the answer says which. A name GitHub refuses for another reason, such as fix/a when a branch fix exists, answers 422 invalid_request.
• Dry runs say whether the name is free, or which suffix it would get, and create nothing.
• Not with newBranch: false, which works on an existing branch: 400 invalid_request.
• Off for your account (Settings → GitHub → Name new branches): 403 branch_naming_off. Leave newBranchName out to start chats as before.

Over MCP, start_chat takes the same as new_branch_name and if_branch_exists.

Send a message

POST /api/v1/chats/{id}/messages, needs the chats:message scope.

Answers 202 with id, url and queued. If the agent is busy, the message is queued behind the current turn, in order, and never interrupts it: queued is true. Otherwise it is sent at once and queued is false.

Read a chat

GET /api/v1/chats/{id}, needs the chats:read scope. Answers 200:

{
  "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "name": "Fix the failing build",
  "status": "running",
  "working": true,
  "repo": "owner/name",
  "baseBranch": "main",
  "branch": "n8v/fix-the-failing-build",
  "pullRequest": null,
  "pullRequestStatus": null,
  "archived": false,
  "pinned": false,
  "unread": false,
  "model": null,
  "createdAt": "2026-10-03T12:00:00.000Z",
  "updatedAt": "2026-10-03T12:03:10.000Z",
  "lastError": null,
  "pendingWork": null,
  "waitingFor": []
}

working is true for queued and running. It is the same test the API uses to decide whether a message queues.

pinned and unread are as your task list shows them. model is the model the chat's next message runs on when it names none, set with PATCH; null means the model it last used.

pullRequestStatus is the chat's pull request in full, as Pull request and CI answers it, or null while it has none. With the feature switched off it is left out; pullRequest is always the number.

lastError is null unless the chat stopped on an error, and again once it runs. It is never named error, the key of the API's own failures:

pendingWork is null unless the chat's last turn ended while work it started was still running: a background task or monitor its agent stopped on exit, or a process it left behind. Nothing reports back on that work, so the chat says so instead of finishing silently. message says what to do; each of items has kind (task or process), label (the command, when known) and endedAt. The next turn clears it. Being rolled out: an account without it always gets null.

waitingFor lists what a running chat waits for after its turn ended, with its agent environment paused: kind event (the agent's wait_for) or wake_up (a timed wake-up), its reason and until, the deadline. Empty otherwise.

Pull request and CI

GET /api/v1/chats/{id}/pull-request, needs the chats:read scope. Where the chat's work stands on GitHub: the pull request's state, conflicts, reviews, each CI check with the link to its log, the commit that landed on main, and whether production serves it. Read-only, through the n8v GitHub App. Answers 200:

{
  "repo": "owner/name",
  "number": 812,
  "url": "https://github.com/owner/name/pull/812",
  "title": "Fix the failing build",
  "state": "merged",
  "mergedAt": "2026-11-08T09:12:40Z",
  "closedAt": "2026-11-08T09:12:40Z",
  "base": "main",
  "head": "n8v/fix-the-failing-build",
  "headSha": "9a060f81b9ff2418042d1988b9ef9e2f18789f57",
  "conflicts": null,
  "mergeState": "unknown",
  "review": {
    "decision": "approved",
    "approvedBy": ["octocat"],
    "changesBy": [],
    "requested": []
  },
  "checks": {
    "state": "passing",
    "passed": 5,
    "failed": 0,
    "pending": 0,
    "skipped": 1,
    "runs": [
      {
        "name": "ci",
        "state": "passed",
        "conclusion": "success",
        "url": "https://github.com/owner/name/actions/runs/42438605575/job/128602806823",
        "required": true
      }
    ],
    "more": 0,
    "why": null,
    "fix": null
  },
  "main": {
    "branch": "main",
    "commit": "ad8e67dae6c879c3a330abaa290825be77260889",
    "onMain": true
  },
  "deploy": {
    "live": true,
    "source": "github",
    "environments": [
      {
        "name": "Production",
        "commit": "ca400ad91d9e4f6e5696f2d524f5895360a52567",
        "url": "https://example.com",
        "at": "2026-11-08T09:18:16Z",
        "live": true,
        "failed": false
      }
    ],
    "why": null,
    "fix": null
  },
  "checkedAt": "2026-11-08T09:20:02.000Z",
  "stale": false,
  "unavailable": null
}

A part GitHub withholds says why in its why (permission, rate_limited, github_unavailable) and what to do in fix. Checks need the n8v GitHub App's Checks permission, and production its Deployments permission, each approved for your account or organization on GitHub. For n8v's own repository, production is what the live domains serve. A merged change counts as live once the commit production serves contains it.

Answers are cached for up to 45 seconds while the pull request is open, and for longer once it is live or closed; a GitHub webhook about it clears the cache. ?refresh=true asks GitHub again (at most every 10 seconds). n8v keeps part of each installation's GitHub budget for your agents' own work: near the limit, it answers from cache with stale: true.

A chat without a pull request answers 404 no_pull_request; one that no longer exists on GitHub, 404 pull_request_not_found; a repository the app cannot read, 403 github_no_access; GitHub down or at its limit, 503 github_unavailable with Retry-After. Switch it off for every key and assistant of your account under Settings, API, Reading chats, Pull requests and CI: then this answers 403 pr_status_off.

Read messages

GET /api/v1/chats/{id}/messages, needs the chats:read scope. One page of a chat, newest last. A chat can run to megabytes, mostly the agent's tool output, so a page is light by default: ask for more only where you need it.

curl -sS --fail-with-body -G https://n8v.online/api/v1/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $N8V_API_KEY" \
  --data-urlencode "only=summaries"

{
  "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "only": "summaries",
  "messages": [
    {
      "id": "120",
      "role": "assistant",
      "text": "The build fails on a missing env var in CI. I added it to the workflow and the tests pass.",
      "at": "2026-11-05T09:20:11.000Z"
    }
  ],
  "moreBefore": "118"
}

role is user, assistant, tool, error, result or system; at is null when the chat did not store a time. A message is clipped at 12,000 characters, ending in … [clipped, N characters in total]; Read one step shows it all. A page is held to about 60,000 characters: the oldest messages are dropped first, and moreBefore then points at the first one kept. moreBefore is null at the start of the chat; otherwise pass it as before for the page before.

Read one step

GET /api/v1/chats/{id}/messages/{messageId}, needs the chats:read scope. One step in full, without loading the rest of the chat: a tool call with its input and its output, or one message. For a tool step, the id of the call and the id of its result both work. Ids come from Read messages, Search messages and clipped text.

Answers 200:

{
  "chatId": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
  "messageId": "130",
  "resultId": "131",
  "role": "tool",
  "name": "Bash",
  "error": false,
  "at": "2026-11-05T09:18:02.000Z",
  "text": "Tool call: Bash\nInput:\n{\"command\": \"pnpm test\"}\n\nOutput:\n...",
  "offset": 0,
  "total": 54321,
  "nextOffset": 20000
}

For a tool step, messageId is the call's id and resultId its result's (null while the tool runs, and for a message); name is the tool's, null for a message, and error is true when the tool failed. total counts the whole step. nextOffset is null on the last page; otherwise pass it as offset to read on.

Search messages

GET /api/v1/search/messages, needs the chats:read scope. Finds what was said in your chats: the text of your messages and of the agents' replies, never tool output, thinking or a subagent's messages. Newest first.

curl -sS --fail-with-body -G https://n8v.online/api/v1/search/messages \
  -H "Authorization: Bearer $N8V_API_KEY" \
  --data-urlencode 'q=deploy "staging only" -preview' \
  --data-urlencode "author=owner"

{
  "results": [
    {
      "messageId": "48213",
      "chatId": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
      "chatTitle": "Fix the failing build",
      "repo": "owner/name",
      "author": "owner",
      "at": "2026-11-05T09:12:44.000Z",
      "snippet": "…the tests are green. Now deploy to staging only and run the smoke tests before you open the pull…",
      "archived": false,
      "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11"
    }
  ],
  "nextCursor": "48213"
}

author in a result is owner, agent or supervisor: a message one of your supervisors sent into the chat, which author=owner leaves out. snippet is up to 240 characters around the first match, with … where it was cut. nextCursor is null on the last page. To read a result in full, pass its messageId to Read one step; to see what led to it, Read messages with before set to messageId plus one.

A key limited to repositories searches only those: a repo outside them finds nothing, a chat outside them answers 403 repo_not_allowed. A chat from before n8v's current message store is found once it has been opened once. A search that runs for more than 5 seconds stops: narrow it with a chat, repository, author or dates, or with more specific words.

Message search is on for every account. An admin can switch it off in Settings, API, under Reading chats; these three endpoints then answer 403 message_search_off, and Read a chat still works. Authentication, X-Request-Id, caching and 405 work as for every endpoint, and every call counts against the per-key limit. The audit log records every call, never the words searched for or the answers: they hold what was said.

What runs now

GET /api/v1/now, needs the chats:read scope. What the Now board in the app shows: every chat whose agent is running, with the step it is on; the chats that wait for you; and the latest steps across all of them. Only the key's repositories count. Answers 200:

{
  "counts": { "running": 2, "needsYou": 1 },
  "running": [
    {
      "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
      "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
      "name": "Fix the failing build",
      "repo": "owner/name",
      "branch": "n8v/fix-the-failing-build",
      "pullRequest": null,
      "pullRequestStatus": null,
      "agent": "claudeCode",
      "status": "running",
      "working": true,
      "updatedAt": "2026-11-02T10:05:31.000Z",
      "pulse": {
        "doing": { "kind": "tool", "name": "Bash", "title": "Run the tests" },
        "since": "2026-11-02T10:05:30.000Z",
        "started": "2026-11-02T10:00:00.000Z",
        "partial": false,
        "steps": 14,
        "edits": 3,
        "said": "Tests are green except one.",
        "failed": false,
        "recent": [
          {
            "id": "812",
            "name": "Bash",
            "title": "Run the tests",
            "at": "2026-11-02T10:05:30.000Z",
            "open": true,
            "failed": false
          }
        ]
      }
    }
  ],
  "needsYou": [
    {
      "id": "0b7e9f7a-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "Ship the docs",
      "status": "complete",
      "working": false,
      "reason": "ready"
    }
  ],
  "activity": [
    {
      "chatId": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
      "name": "Fix the failing build",
      "step": { "id": "812", "name": "Bash", "title": "Run the tests" }
    }
  ]
}

(Shortened: every entry of running and needsYou carries the same fields as the first, and every step the same as in recent.)

running lists up to 16 chats and needsYou up to 20, most recently active first; counts counts all of them, so a list shorter than its count was cut. status and working mean what they mean in Read a chat: a queued chat is waiting for an agent environment or a limit.

pulse is null while a chat starts, before it has stored anything. A chat in needsYou has a reason: ready when it finished and you have not read it yet, failed when it stopped on an error (GET /api/v1/chats/{id} says why). activity holds the latest 8 steps across the running chats, newest first, as the board shows them. Each chat carries pullRequestStatus in brief, as List chats does.

The audit log records the call and the counts, not the answer: it is large and changes by the second.

Usage and spend

GET /api/v1/usage, needs the chats:read scope. What your agents cost and used in a period, grouped one way, with the period before for comparison. It answers "what did I spend this week, and on what?" in one call.

curl -sS "https://n8v.online/api/v1/usage?period=week&by=model&timezone=Europe/Amsterdam" \
  -H "Authorization: Bearer $N8V_API_KEY"

Answers 200:

{
  "period": {
    "name": "week",
    "timezone": "Europe/Amsterdam",
    "from": "2026-11-01T23:00:00.000Z",
    "to": "2026-11-07T13:30:00.000Z"
  },
  "by": "model",
  "total": {
    "costUsd": 42.1,
    "reportedUsd": 40,
    "estimatedUsd": 2.1,
    "chargedUsd": 0.4,
    "tokens": { "input": 120000, "cacheRead": 9800000, "cacheWrite": 410000, "output": 230000, "total": 10560000 },
    "agentMs": 11400000,
    "turns": 25,
    "chats": 12
  },
  "previous": {
    "from": "2026-10-25T23:00:00.000Z",
    "to": "2026-10-31T13:30:00.000Z",
    "costUsd": 37.6
  },
  "groups": [
    {
      "key": "opus-5.5",
      "name": "Opus 5.5",
      "share": 0.71,
      "costUsd": 30,
      "reportedUsd": 30,
      "estimatedUsd": 0,
      "chargedUsd": 0,
      "tokens": { "input": 80000, "cacheRead": 7000000, "cacheWrite": 300000, "output": 160000, "total": 7540000 },
      "agentMs": 7800000,
      "turns": 18,
      "chats": 9
    }
  ],
  "more": 0
}

(Shortened: previous carries every field of total.)

Usage and spend cover every repository, so a key limited to repositories gets 403 repo_not_allowed. chats counts each chat once per group and once in total. Turns before November 7, 2026 have no recorded model: they are listed as Model not recorded. The API answers with the period's totals, never the individual usage rows.

Statistics

GET /api/v1/stats, needs the chats:read scope. The numbers the Stats page shows, for the last days days with today (1 to 365, default 30; accounts without the longer ranges see at most 30), in timezone (default UTC). Answers 200 with days, maxDays, timezone, summary (tasks, prs merged, finished, agentMs, runs, tokens), previous (the same for the days before, or null), daily (one entry per day, oldest first), repos (the five busiest), tokensByProvider and tokensByRepo. Fields the Stats page does not show for your account are null. A key limited to repositories gets 403 repo_not_allowed.

Both endpoints answer 403 usage_disabled when Settings, API, Usage and statistics is off for your account.

Retention overview

GET /api/v1/privacy/retention, needs the chats:read scope. What n8v keeps and for how long, rule by rule, and what enforces it. It returns counts, times and codes, never anyone's data. Answers 200 with generated_at, flags (retention_jobs, retention_content) and rules:

Dry run means the job counted what it would remove and removed nothing. Contradicted means the period applied differs from the one the legal page states; why says how. While the overview is off for your account the endpoint answers 403 retention_overview_off. Over MCP: retention_overview.

curl -sS "https://n8v.online/api/v1/privacy/retention" \
  -H "Authorization: Bearer $N8V_API_KEY"

Agent environments

GET /api/v1/agent-environments, needs the chats:read scope. How many of your tasks run in an agent environment now, of how many may run at once, and how many wait. Use it before starting many chats.

GET /api/v1/sandboxes is the same call under its earlier name. It still works and answers exactly the same, but it is deprecated: use agent-environments in new code. Paths, error codes and the MCP tool name sandboxes keep their earlier spelling so that nothing you built breaks.

{
  "running": 12,
  "waiting": 0,
  "limit": 20,
  "tier": "pro",
  "source": "account",
  "summary": "12 of 20 agent environments running"
}

A chat started over the limit is not refused: its status is queued until an agent environment is free. The count covers every repository, so a key limited to repositories gets 403 repo_not_allowed. While agent environment limits are off for your account the answer is 403 sandbox_limits_disabled.

What changed: events

GET /api/v1/events, needs chats:read for chat and automation events, organizations:read for organization events, or both. One call tells you what happened since you last looked; an assistant that cannot be notified calls it at the start of every conversation. Only the key's repositories count. Answers 200, oldest first:

{
  "events": [
    {
      "id": "8f8c3c0e-6a0e-4d0b-9a1e-1b6d1c2f3a4b",
      "type": "chat.failed",
      "createdAt": "2026-11-07T09:41:12.000Z",
      "data": {
        "chat": {
          "id": "5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
          "url": "https://n8v.online/task/5f0c0d6e-8a0b-4e0e-9a54-7a1a5f7a0c11",
          "name": "Fix the failing build",
          "repo": "owner/name",
          "branch": "n8v/fix-the-failing-build",
          "pullRequest": 128,
          "agent": "claudeCode"
        },
        "error": {
          "code": "agent_generic_error",
          "message": "The agent stopped with an error.",
          "retry": "yes"
        }
      }
    }
  ],
  "nextCursor": "4412",
  "hasMore": false
}

Keep nextCursor and pass it as since next time: you get each event once, in order. It moves on even when nothing matched, so an empty answer still has one. Events appear two seconds after they happen, so that two that are written at the same moment are always seen in order, and are kept 30 days.

Stopping a chat yourself records nothing, nor do the tasks agents run inside an organization: they ask through the organization. The same events go to your webhooks. Turn them off for your account in Settings, General, Events and webhooks: nothing is recorded or sent while they are off, deliveries still waiting for a retry end unsent, and these calls answer 403 events_disabled.

Webhooks

A webhook sends each event you choose to your endpoint as it happens: a JSON POST whose body is the event exactly as GET /api/v1/events shows it. Add and manage them in Settings, API, Webhooks, or with these calls, which need the webhooks:manage scope. A key adds or changes only a webhook whose events it could read itself: chats:read for chat and automation events, organizations:read for organization events, both for *. A key limited to repositories cannot add or change one, because a webhook hears every repository.

curl -sS https://n8v.online/api/v1/webhooks \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url": "https://example.com/n8v/events", "events": ["chat.failed", "chat.needs_you", "org.*"]}'

Send an Idempotency-Key when you add one: a retry then answers the same webhook and the same secret instead of adding a second. Once the secret has been rotated, a retry answers secret: null.

Verify a delivery

Every request carries:

Check the signature against the raw body before you parse it, and refuse a t more than five minutes old, so a captured request cannot be replayed later:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(raw: string, header: string, secret: string) {
  const p = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(p.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const want = createHmac("sha256", secret).update(`${p.t}.${raw}`).digest();
  const got = Buffer.from(p.v1 ?? "", "hex");
  return got.length === want.length && timingSafeEqual(got, want);
}

Answer any 2xx within 10 seconds; do the work afterwards. Anything else, a timeout or a redirect counts as a failure and is tried again after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours: 8 attempts over about two days. Each attempt is signed anew, with the same body, so use the event's id to ignore one you already handled. After 5 events in a row that used every attempt, n8v pauses the webhook and Settings says why; fix the endpoint, send a test event and turn it back on. The delivery log keeps each delivery's status, your endpoint's status code, how long it took and the attempts, never what your endpoint answered, for up to 30 days; a delivery that has settled (delivered, or out of attempts) may be removed 7 days after its last attempt, and can no longer be sent again from the log after that. n8v sends only to public addresses, checked again on every attempt.

Retry a chat

POST /api/v1/chats/{id}/retry, needs the chats:message scope. Runs a chat that stopped on an error again, like Retry in the app: a failed commit or push is checkpointed again, any other error runs the last turn again. A chat waiting for a usage limit resumes now when the account may (agentRateLimitRetry). When its model was refused (lastError.retry is with_another_model), model sends the same message again with another one, like Send again with in the app.

Answers 202 with id, url and model: the model the message was sent with, or null for a plain retry. The message itself never changes. The chat records that it was sent again, with which model and that it came from the API or MCP, and the agent receives it unchanged.

Stop a chat

POST /api/v1/chats/{id}/stop, needs the chats:message scope, no body. Stops the agent's turn, like Stop in the app. Nothing is deleted: a message continues the chat. Answers 200 with id, url and stopped. stopped is false when nothing was running, such as a second call or an agent that finished first; that is an answer, not an error.

Fast-forward a chat

POST /api/v1/chats/{id}/forward, needs the chats:message scope, no body. Sends your saved Fast-Forward prompt (by default proceed, set in Settings), like Fast-Forward in the app. While the agent works, the prompt waits behind its turn. Answers 202 with id, url and queued.

Calling again while that prompt still waits, or before the agent answered it, changes nothing. Once the agent has answered, a call sends the prompt again, so send an Idempotency-Key: a retry with it answers what the first call did, even when the agent has answered since.

Where repository instructions are on for the account, the prompt is composed: your saved prompt, then the Fast Forward instructions in force for the chat, then message, the words this call adds (up to 4,000 characters). The answer then also carries message, the text as sent, and parts, each with its text and from (account, repo, chat or call). Send {"dryRun": true} to get that message without sending: 200 with dryRun: true, sent: false, message and parts. A dry run makes every check a real call makes, and is never the answer a later call's Idempotency-Key gets.

curl -sS -X POST "https://n8v.online/api/v1/chats/$CHAT_ID/forward" \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dryRun": true}'

Archive a chat

POST /api/v1/chats/{id}/archive, needs the chats:message scope. Archives a chat, like Archive in the app: its agent stops, the chat is unpinned, marked read and leaves your list. Nothing is deleted. With Close your pull requests when task is archived on in Settings, GitHub, an open pull request you created for this chat alone is closed, as it is from the app. Send {"archived": false} to bring the chat back; its pull request stays as it is. Answers 200 with id, url and archived. An organization agent's task belongs to its organization and answers 409 refused.

List chats

GET /api/v1/chats, needs the chats:read scope. Your chats in the key's repositories, most recently active first. Every parameter is optional and they combine, so "what failed this week" is one call:

curl -s "https://n8v.online/api/v1/chats?status=error&from=2026-11-02" \
  -H "Authorization: Bearer $N8V_API_KEY"

What merged today, and what fails CI:

curl -s "https://n8v.online/api/v1/chats?dateField=merged&from=2026-11-08" \
  -H "Authorization: Bearer $N8V_API_KEY"
curl -s "https://n8v.online/api/v1/chats?prState=open,draft&checks=failing" \
  -H "Authorization: Bearer $N8V_API_KEY"

Before a pull request filter runs, n8v asks GitHub about your open pull requests (up to 100, most recently active first), so it matches what GitHub says now. When it cannot see something a filter asks about, such as checks the GitHub App may not read yet, the answer says so in notes.

Answers 200 with chats and nextCursor (null on the last page). Each chat has id, url, name, status, working, repo, branch, pullRequest, pullRequestStatus, pinned, unread, archived, tags, topic, createdAt and updatedAt. tags is a list of {id, name, color} and topic is {id, name} or null; each is there while tags and topics are on for your account. pullRequestStatus is the pull request in brief, or null without one: number, url, state, checks, failing (the names of the failed checks), conflicts, review, onMain, live, and unavailable (why GitHub could not be read, or null). The list waits at most 4 seconds on GitHub; a pull request it could not read in time says github_unavailable. Here status is error for a chat whose last run stopped on an error, which reading the chat shows as lastError. An organization, automation, tag or topic you do not have answers 404 organization_not_found, 404 automation_not_found, 404 tag_not_found or 404 topic_not_found.

Subscription quotas and alternatives

GET /api/v1/subscriptions, scope chats:read. The MCP tool is subscriptions. Settings > API > Subscriptions and quota shows the same overview and controls access. It is on by default. Repository-restricted keys cannot read this account-wide information.

curl -sS --fail-with-body -G https://n8v.online/api/v1/subscriptions \
  -H "Authorization: Bearer $N8V_API_KEY" \
  --data-urlencode "chat_id=$CHAT_ID" \
  --data-urlencode "intent=coding"

subscriptions contains connected credentials with numbered labels such as Claude #2. It never contains account emails, account identifiers, credential IDs, custom credential labels, provider URLs or raw provider messages.

Each entry gives provider, agent, kind, selected, status, availability, source, observedAt, stale, windows and resetsAt. Statuses are active, rate_limited, logged_out, error and disabled (turned off, listed only with include_disabled; Turn a subscription off). Active means connected; only availability: "available" means a recent reading confirms headroom. Missing quota is unknown, never zero or unlimited.

Quota windows show usedPct against limitPct: 100, their model scope, window duration and reset time. After a reset passes, usage becomes null until another reading confirms it. Stale data remains labelled stale. API keys and providers without quota readings remain visible with unknown usage. Claude, ChatGPT/Codex and Grok use n8v's existing quota readers. Connected OpenRouter keys also return spend with used, limit, remaining, period and unit: "USD". Their key limits reset at the provider's documented UTC boundary. Key allowance does not establish account credit balance, so remaining key budget alone never becomes a confirmed alternative. CLI exhaustion observed on a recorded turn takes precedence over a healthy cached reading.

chats lists blocked chats, their model, retryAt, any safe resetHint, and an alternative. A retry time belongs to n8v's scheduler and is not necessarily a provider reset. A date-only hint such as Nov 11 does not claim an hour or timezone. Unattributed historical errors are reported on the chat, never assigned to whichever subscription happens to be selected now.

Alternatives use enabled models with fresh quota and respect provider-switch access. requiresActivation: true means the subscription must first be made active, with POST /api/v1/subscriptions/active or in Settings > Agent; this may affect other chats on that provider. Reading the overview never switches accounts or models. Coding hints can suggest GPT-6 Astra when enabled and available. For long creative or video work, the hint suggests considering a wait to preserve continuity. These are workflow hints, not model quality benchmarks.

To switch, call update_chat with chat_id and the suggested model, or use the PATCH endpoint below. Send a follow-up when ready to continue; changing settings alone does not resume a stopped chat.

Quota planning

Planning is being rolled out per account with quotaPlanning, off by default. It also requires the existing quota permissions. Administrators can enable it at /internal/admin/feature-flags.

GET /api/v1/subscriptions/plan, scope chats:read, matches MCP quota_plan. Optional query: intent=coding|creative|video|general; omit it for all rankings. Turned-off subscriptions are never counted; disabled names them, and include_disabled=true lists them in subscriptions with state disabled. It uses the subscription overview permission and refuses repository-restricted keys because the view is account-wide.

The response contains generatedAt, subscriptions, room, expiring, blocked, unknown, recommend, fitSource and note. Subscriptions use private numbered labels, never account ids or emails. Each has state, headroomPct, blockedUntil, reading time/age/staleness, billing period/source, and windows with remaining percentage, reset, 24-hour/7-day burn rates, projected use and unused allowance. With limits per model on, each subscription also has usageWindows (every window with scope: shared or one model family) and the response has families, the ranking per Claude model; see Usage windows by scope. Missing values are null. Rates state their observed hours; lowerBound: true means a gap may hide usage across a reset.

Recommendations contain subscription, model, model headroom, reason and whether switching is needed. Stale or unknown readings are not recommendations. API keys come after subscriptions with confirmed room and are labelled billed per request. Model fit is null when no capability score is available.

POST /api/v1/subscriptions/renewal, scope chats:message, matches MCP set_renewal:

{"subscription":"Claude #2","renews_at":"2026-11-14","period":"month"}

renews_at accepts a date or an ISO time with a zone, within five years of now. period is week, month (default) or year. Any one renewal date anchors the repeating schedule. Pass null to clear it. The response gives the current renews_at, period_start, period and a note. Changes are audited as limit.renewal_set.

A current provider-reported period takes precedence over an entered date. Expired provider evidence becomes unknown; only an owner's explicit recurring schedule is advanced. Billing renewal alone does not imply quota expiry. Quota explains provider evidence and forecasts.

Forecast

With quotaForecast on for the account, GET /api/v1/subscriptions/plan adds forecast, and takes margin (0 to 100, the safety margin in percent, default 20; anything else answers 400). MCP quota_plan takes the same margin as a number. The field holds:

• subscriptions: per subscription its plan (id, name, units, usd, and source: owner, detected or assumed, or null when not known), the followed window, last7d and last30d (rate in points an hour, hours, cappedPct, r2, se), utilization, full, fullAt, history and projection as [time, percent] pairs.
• pools: per provider supplyUnits, unpriced (labels whose plan or weekly capacity is unknown), last7d and last30d in units a week, models (use: linear, exponential, seasonal or exponential_seasonal, with why), saturated, atLimitPct, dryNow, dryAt, dryHoursPerWeek, range (pace low and high, dryAt early and late, why) and need (units short with the margin, negative is spare).
• advice.last_7d and advice.last_30d: cheapest and fable options, each with buy (plan, count, cost, units, Fable units), count, monthlyUsd, and where it applies moved, uncovered; and unmeasured, the providers at their limit throughout.
• total (dryAt, history, projection), basis, headline, notes, margin, preference and catalogAsOf.

No credential id leaves the server. The plan of a subscription is set in Settings, Agent and audited as limit.plan_set. Quota explains the method.

Switch and steer subscriptions

Every change the Quota page offers is available here and as MCP tools. Subscriptions are named by the numbered label GET /api/v1/subscriptions gives them (Claude #2), never by email or id. Changes need the chats:message scope, reading events chats:read; a key limited to repositories is refused (403 repo_not_allowed), because they affect the whole account. Every call is written to the audit log.

A limit that is one model's (Fable out while Opus still runs) has its own rule: GET and POST /api/v1/subscriptions/model-fallback, MCP set_model_fallback. See Limits and fallback per model.

The last step at a limit, the best model that has room right now by your preference order and benchmark table: GET and POST /api/v1/subscriptions/benchmark-fallback and its /dry-run, MCP get_benchmark_fallback, set_benchmark_fallback and dry_run_benchmark_fallback. See Benchmark-aware fallback.

A switch applies to every chat of that provider from its next message; a chat in the middle of a turn finishes it on the previous account. Only Claude and OpenAI subscriptions can opt in to auto-switch. GET /api/v1/subscriptions also returns, for each subscription, health (ok, limited, stale, relogin or unavailable), autoSwitch (eligible, enabled, rank) and models (what limits each model on that account), and a control block with the defaultModel, the chats a switch would touch (impact) and the fallback order per provider.

Cross-provider fallback

With the fallback on, a chat whose provider has no subscription left after auto-switch, or that fails again after one automatic retry, continues on another provider's model with its whole conversation and repository, instead of waiting for the reset. By default Claude chats continue on GPT-6 Astra, GPT chats on Opus 5.5 and Gemini chats on GPT-6 Astra, at the closest effort (Opus 5.5 High continues as GPT-6 Astra High). The first turn after the provider's reset goes back to the chat's own model, unless back is off. It runs only on your own connected subscriptions and keys, never on n8v's credits, and never for an organization's runs.

The chat shows a line where it moved and where it came back, and a Fallback badge beside its model. GET /api/v1/chats/{id} (MCP read_chat) returns modelPinned and fallback (active, from, to, reason, since, until, back, endedAt, end); GET /api/v1/now (MCP now) returns fallback for running chats on one; GET /api/v1/subscriptions returns the setting as fallback and each chat's state. PATCH /api/v1/chats/{id} with {"modelPinned": true} (MCP update_chat with model_pinned) keeps a chat on its model: it never falls back and never returns by itself. Each move is in the audit log (limit.fallback, limit.fallback_return) and in the event feed (chat.fallback.started, chat.fallback.ended). Refusal: 403 fallback_off.

Refusals: 403 subscriptions_disabled (the overview is off for the account), 403 switching_disabled, 403 auto_switch_disabled, 404 subscription_not_found (no subscription has that label), 400 invalid_request.

Change a chat's settings

PATCH /api/v1/chats/{id}, needs the chats:message scope. Send only what should change; nothing is sent to the agent.

Answers 200 with id, url, name, pinned, unread, model, peers when you sent it, instructions when you sent it (the chat's own standing and fastForward as they now stand), and tags and topic as in List chats. Every field is checked before anything changes: a tag or topic you do not have answers 404 tag_not_found or 404 topic_not_found and nothing is changed. A model of another agent answers 422 other_agent unless the chat can switch agents. Setting the same values again changes nothing, so a retry is safe.

A model update also requires the Subscription overview and model switching setting. Cross-provider changes require the existing chatProviderSwitch access flag and usable destination credentials. Otherwise the response explains other_agent or credentials_required, before any requested setting changes. The returned switch object includes agent, applies: "next_turn", context (same_agent or transcript_replay) and a warning.

A provider switch keeps the repository and replays the conversation as text. Native sessions, thinking and provider-specific tool state do not transfer; tool results are shortened and older history may be trimmed. The active turn continues unchanged. A queued message that explicitly names a model keeps its own choice. model: null restores the last-used model.

Act on many chats

POST /api/v1/chats/bulk, needs the chats:message scope. One action on up to 50 chats:

{ "action": "archive", "ids": ["5f0c0d6e-...", "a1b2c3d4-..."] }

{ "action": "tag", "ids": ["5f0c0d6e-...", "a1b2c3d4-..."], "tags": ["bug"] }

tags goes only with tag and untag, topic only with set_topic; each is required there. Both are checked before any chat is touched.

Answers 200 with action, succeeded, failed and results, one per chat in the order sent (a repeated id counts once). Each result is {"id", "ok": true}, with changed for stop (false: nothing was running) and for tag, untag and set_topic (false: it was so already), or {"id", "ok": false, "code", "message"} with the same code the single-chat call would answer, such as chat_not_found or repo_not_allowed. One chat that cannot be done never fails the others. Every action can be repeated safely, so a retry needs no Idempotency-Key. Each chat counts as one call toward the key's limit: over it, the answer is 429 rate_limited and no chat is touched.

Tags and topics

You organize chats in the app's list two ways, and the API does the same:

• Tags: as many per chat as you like, each with a name and a color. The list filters by them and can group by them.
• Topics: the list's categories. A chat is in at most one; chats in none show under No topic. Pinned topics show first.

They work while tags or topics are on for your account; otherwise their calls answer 403 tags_off or 403 topics_off. Put them on chats with Change a chat's settings or Act on many chats, and find chats by them with List chats. Wherever a path takes {id}, the name works too, in any case and URL-encoded (/tags/needs%20review).

The rules are the app's. A tag's name is 1 to 32 characters and its color one of slate, red, amber, green, teal, blue, violet or pink. A topic's name is 1 to 64 characters and never "No topic". Names are trimmed and unique ignoring case: a taken one answers 409 tag_exists or 409 topic_exists. Deleting a tag or topic never deletes a chat. Tags and topics reach every chat, so only a key for all repositories can create, change or delete them (403 forbidden); any key can list them and use them on the chats it reaches. Open tabs of the app show every change at once.

Agent environment health and recovery

Every chat runs in its own agent environment. While its agent works, n8v saves the work in progress at the first file edit, every few minutes after, and at the end of every turn: uncommitted and untracked files (never ones git ignores, nor untracked files over 20 MB) go to a hidden ref of the repository, refs/n8v/wip/{chat id}/{sandbox id}, never to the branch's history. Each agent environment writes only its own ref, so a rebuilt agent environment never writes over the work it came from. The chat's branch exists on GitHub from the first save. A turn that ends with everything committed and pushed removes the ref again, and deleting the chat removes all of them. Chats with git checkpointing off are not saved this way, and neither is work in a public repository mid-turn: there the turn's own checkpoint is the save, as before.

GET /api/v1/chats/{id}/sandbox, needs the chats:read scope. Answers 200 with id, url and sandbox:

POST /api/v1/chats/{id}/sandbox/resume, needs chats:message, no body. Resumes a paused agent environment again: one try at once, then up to 5 in all, 1, 2, 4 and 8 minutes apart. On success the work is saved first; then a chat whose start failed on its agent environment runs again, and otherwise the agent environment goes back to sleep. Answers 202 with the sandbox as it is now; read it again for the outcome.

POST /api/v1/chats/{id}/sandbox/rebuild, needs chats:message. Gives the chat a fresh agent environment built from its last checkpoint: its branch, then the saved work in progress put back as uncommitted changes. When the branch moved on since (another push, "Update branch"), the work is brought onto it; if that conflicts, the save is kept and listed under kept, never discarded. The chat then goes on with its whole conversation: a start that failed on its agent environment runs again, a queued message is sent; otherwise the next message builds it. Send {"size": "large"} for a larger agent environment where the account has one. While the last save failed and the agent environment can still be read, it answers 409 unsaved_work: export first, or send {"force": true}. Answers 200 with continued and the sandbox. Files git ignores, such as .env, are not kept.

POST /api/v1/chats/{id}/sandbox/export, needs chats:message. Resumes the agent environment if needed, saves everything it holds that is not on the branch yet, and answers 200 with sha, branch, files, commits, skipped, url (the snapshot on GitHub), compareUrl (everything since the base branch), and patch with truncated: a binary patch of all of it, up to 1 MB, or maxPatchBytes. Send {"patch": false} to leave the patch out.

Each of the three actions counts as 5 calls toward the key's limit, since each resumes or builds an agent environment.

Prepared prompts

Your prepared prompts are the saved prompts the composer offers, edited in Settings, Agent, Prepared Prompts. Over the API you can read them, send them exactly as the composer does, and change them. They work where prepared prompts are on for your account, and you can turn their use over the API and MCP off, for your account alone, in Settings, API & MCP, Prepared prompts. Otherwise every call answers 403 prompts_off.

Wherever a path takes {id}, the prompt's title works too, in any case and URL-encoded (/prompts/Review%20code). A title two prompts share answers 404 prompt_not_found: use the id.

Read them

GET /api/v1/prompts, needs the chats:read scope. Answers 200 with prompts, in your order, defaults and max (12, the most the library holds):

{
  "prompts": [
    {
      "id": "c1f4...",
      "title": "Review PR",
      "body": "Review pull request {{pr}}, strict about {{focus}}.",
      "variables": ["pr", "focus"],
      "position": 1
    }
  ],
  "defaults": false,
  "max": 12
}

defaults is true while you have not saved prompts of your own: the list is then n8v's starter prompts, as the composer shows them. Once you removed them all, the list is empty. GET /api/v1/prompts/{id} reads one.

Variables

{{name}} in a prompt's text marks a value to fill in each time it is sent: a letter, then up to 39 letters, digits, _, . or -, with spaces inside the braces allowed. variables lists each once, in order. The composer in the app puts the text in as written, for you to edit; over the API, send a value for each in variables. A prompt without them is sent as written.

Start a chat with a prompt

POST /api/v1/prompts/{id}/start, needs the chats:create scope:

curl -sS -X POST https://n8v.online/api/v1/prompts/Review%20PR/start \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"repo": "owner/name", "variables": {"pr": "#42", "focus": "auth"}}'

It is Start a chat with the prompt as its message: the same checks, the same 202 answer with prompt (id, title) added, the same idempotency and the same hourly limit on new chats.

Send a prompt into a chat

POST /api/v1/prompts/{id}/send, needs the chats:message scope. The body takes chatId, and model, variables, note and dryRun as above. It is Send a message with the prompt as the message: queued while the agent works, answered 202 with id, url, queued and prompt.

A dry run of either answers 200 with message, the exact text it would send. Use it to read a prompt back before it goes.

With an Idempotency-Key, a retry of either answers the first call (200, Idempotent-Replayed: true), even once the prompt was changed or deleted. The key is held against the body you sent and the prompt the path names: the same key for another prompt answers 422 idempotency_conflict.

Every other answer is the one of Start a chat or Send a message.

Change them

These need the chats:message scope and a key for all repositories: prompts are for the whole account, so a key limited to some repositories answers 403 forbidden. A change shows in the app's composers at once.

• POST /api/v1/prompts with title (up to 200 characters), body (up to 20,000) and optionally position (1 is first; the end by default) adds a prompt and answers 201 with it. With an Idempotency-Key, a retry answers the first call's prompt and adds nothing. A thirteenth answers 409 prompts_full.
• PATCH /api/v1/prompts/{id} with any of title, body and position changes only those, and answers 200 with the prompt.
• DELETE /api/v1/prompts/{id} deletes it and answers 200 with id, title and deleted.

While you have not saved your own prompts, the first change starts from n8v's starter prompts, as Settings does.

Supervisors

A supervisor is a model that manages a group of your chats: when one finishes, errors or stops, and on its schedule, it reviews the group and, by its mode, reports, recommends, or messages the chats and decides that they wait or are finished. These calls manage them as the Supervisors page does, with the same rules.

They need the supervisors:read or supervisors:write scope, supervisors on your account, and Assistants and keys can manage supervisors on in Settings, API (on by default). A key limited to repositories is refused (403 repo_not_allowed): a supervisor manages chats on any repository. In every path, {id} is the supervisor's id or its name in any case.

Pause and resume answer 200 with state and changed (false when it already was). Delete answers 200 with {"id", "name", "deleted": true}.

Create a supervisor

curl -X POST https://n8v.online/api/v1/supervisors \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-train-1" \
  -d '{
    "name": "Release",
    "instructions": "Get the login fix and its docs merged by Friday.",
    "chats": ["<chat id>", "<chat id>"],
    "mode": "autonomous",
    "followUpModel": "sonnet",
    "schedule": { "intervalSeconds": 3600, "quietHours": { "start": "22:00", "end": "07:00" } },
    "limits": { "actionsPerRun": 3, "actionsPerDay": 20 }
  }'

name and instructions are required, and something to manage: chats (up to 10 ids), topics (topic ids, whose chats it manages as they come), or startChat ({"repo", "message"}, a new chat it starts with). milestones (titles, in order) are optional. It reviews its chats at once. Creating one needs a plan, like starting a chat, and honours Idempotency-Key.

Settings

POST takes these, PATCH any of them; whatever you leave out keeps its value (on create, the app's default).

PATCH also takes addChats and removeChats (chat ids). A supervisor manages at most 10 chats. A removed chat stays a chat; topics do not bring it back.

What a supervisor did

GET /api/v1/supervisors/{id}/activity?limit=10 answers runs, newest first, and next. Each run has its status, the triggers that woke it (chatId, what, at), its error and times, and its actions in order, each with a status (in_progress, done or failed) and a kind:

Texts over 4,000 characters are cut, with clipped: true; the chat itself has the whole message. Pass before=<next> for older reviews. Its own reasoning is in its own chat, hubChatId, which Read a chat reads.

Supervisors on a time box

A supervisor can run for a set time with named powers, then end by itself and leave a handover. This is being rolled out per account with timedSupervisors, off by default; administrators enable it at /internal/admin/feature-flags. While it is off these fields and calls answer 403 timed_supervisors_disabled.

POST /api/v1/supervisors and PATCH /api/v1/supervisors/{id} also take:

The first four powers get stuck work moving and decide nothing. answer, approve_plans and queue_merge decide for you: grant them knowingly. Sending a chat a message in its own words is answer: no mechanical power does it. Two powers act today: recover and answer. The others are accepted and shown, and take effect as they are released.

A supervisor with powers acts on its own within them, so mode becomes autonomous; naming powers with another mode is a 400. With powers: [] it only watches: it changes nothing in your chats, in any mode. The server checks every write a supervisor makes against its powers and its time box. A supervisor is told both and cannot change either: only you, or an assistant or key acting for you, can. A time box, once set, is extended or ended, never removed. When two of your supervisors with powers hold the same chat, the one that has held it longest acts on it and the other only observes. A supervisor on a time box holds up to 25 chats.

Powers govern what a supervisor does through n8v. Its own chat has an agent environment like any chat, for reading code and pull requests; it is instructed to change nothing from there, and its running turn is stopped when it ends.

A read answers state (active, paused, ending when its time is up and it is being closed, or ended), timeBox (endsAt, minutesLeft, endedAt, endReason: time, stopped, done or failed), powers, done, and after it ended handover and handoverText.

An ended supervisor is final, from the moment its time is up: resume, pause, changes and new chats answer 409 supervisor_ended, also in the minute before n8v has closed it (state ending). Its chats keep running on their own. Set up a new supervisor to go on. Only a supervisor with a time box or powers can be stopped; one without is paused or deleted (400).

The handover is compiled by n8v from the record, not written by the supervisor, so it exists even when the supervisor could not run: reason, box (from, until, minutes), chats (each with state: finished, working, waiting, needs_you, failed or left, its pr and live, which is null while nothing has verified a deployment), decisions (each write it made: at, chat, power, did, why), needsYou (chat, reason, action, url) and counts. handoverText says the same in a few lines.

Start chats under it. The body is {"chats": [...]}, each item as Start a chat takes it (repo, message, and optionally branch, newBranchName, model; not dryRun). The answer has started, failed and chats in the order sent: {"ok": true, ...} with the chat, or {"ok": false, "repo", "error"}. One that cannot start fails alone. When none started, the answer is the first refusal. With an Idempotency-Key, a retry starts nothing twice; a key belongs to the supervisor it was sent to.

curl -X POST https://n8v.online/api/v1/supervisors/launch-watch/chats \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Idempotency-Key: launch-batch-1" \
  -H "Content-Type: application/json" \
  -d '{"chats": [{"repo": "acme/app", "message": "Add the export button"}, {"repo": "acme/site", "message": "Fix the footer"}]}'

The timeline. GET /api/v1/supervisors/{id}/timeline?limit=20 answers events, newest first, and next; pass before=<next> for older ones. Each has at, kind with its label, actor (kind: person, agent, app or system; label), via, chat, summary, evidence (label, value) and data. Kinds: create, update, extend, pause, resume, stop, end, join, leave, start_chat, check, act, refuse, hand_over, handover. With continuity on for your account, the same entries are in your audit log as kind supervisor.

Peer messaging

Peer messaging is off for a chat until you turn it on: for one chat (PATCH /api/v1/chats/{id} with peers, or the call below), for two you connect, or for every new chat in Settings → Agent → Agent-to-agent messaging. These calls do what a chat's Peers tab does, and let you send between chats and connect two of them yourself. They keep to the key's repositories like every other chat call, and answer 403 peers_off while the feature is off for the account.

GET /api/v1/chats/{id}/peers, needs the chats:read scope. The chat's latest 100 messages with your other chats, both ways, newest first:

{
  "id": "6f1c…",
  "url": "https://n8v.online/task/6f1c…",
  "reachable": true,
  "inReach": true,
  "cutoffHours": 48,
  "messages": [
    {
      "id": "pm-3",
      "direction": "in",
      "chat": { "id": "9a2e…", "name": "API: payments service" },
      "body": "Port 8443. The secret is in STRIPE_WEBHOOK_SECRET.",
      "state": "delivered",
      "route": "live",
      "via": "call",
      "replyTo": "pm-2",
      "conversation": "pm-2",
      "depth": 1,
      "sentAt": "2026-11-04T12:06:00.000Z",
      "deliveredAt": "2026-11-04T12:06:03.000Z",
      "closedAt": null,
      "reason": null,
      "by": "agent"
    }
  ],
  "chats": [
    {
      "id": "9a2e…",
      "name": "API: payments service",
      "repo": "acme/api",
      "branch": "feat/payments",
      "status": "running",
      "activeAt": "2026-11-04T12:09:00.000Z"
    }
  ]
}

reachable says whether agent-to-agent messaging is on for the chat; inReach, whether other chats can reach it now: it takes part, is not archived and ran within the last cutoffHours. A message's direction is out when this chat sent it. route is how the other chat's status sent it on: live (between its steps), queue (behind its turn), wait (with its background work), wake (it started a turn) or hold (you stopped that chat, or its last turn failed: it waits in its queue for your next message there). via says how it reached the agent once delivered: step, finish, call (the answer a waiting MessageChat took) or turn. conversation is the id of the conversation's first message, reason says why one was cancelled or failed, and by is person when you sent it in a chat's name (below), agent when the chat's agent did. chats describes the other chats as they are now, with a status of running, waiting (on background work), idle, failed or unreachable (idle past the cutoff, archived or with agent-to-agent messaging off). A key limited to some repositories sees only the chats, and the messages with chats, in them.

PATCH /api/v1/chats/{id}/peers with {"reachable": true}, needs the chats:message scope. Turns agent-to-agent messaging on for the chat; {"reachable": false} turns it off: your other chats can no longer list, read or message it, and from its next turn its agent has no peer tools. Answers 200 with id, url and reachable.

POST /api/v1/peers/{id}/cancel, needs the chats:message scope, no body. Cancels a message that has not reached its agent yet, one whose state is pending. Answers 200 with the message as GET shows it. A key reaches a message when it reaches either of its chats.

Chats within reach

GET /api/v1/peers, needs the chats:read scope. The chats a message can reach now: active within the last cutoffHours, not archived, with agent-to-agent messaging on. Optional query parameters: q (words in a chat's name, ask or answer), repo (owner/name) and limit (1 to 100, default 50).

{
  "cutoffHours": 48,
  "more": false,
  "chats": [
    {
      "id": "9a2e…",
      "url": "https://n8v.online/task/9a2e…",
      "name": "API: payments service",
      "repo": "acme/api",
      "branch": "feat/payments",
      "prNumber": 412,
      "agent": "claudeCode",
      "status": "running",
      "arrives": "between its steps, within seconds",
      "canReply": true,
      "activeAt": "2026-11-04T12:09:00.000Z",
      "ask": "Add webhook retries",
      "said": "Retries in; tests pass."
    }
  ]
}

arrives says how soon a message would reach the agent, given its status now. canReply is false for agents that receive but cannot answer with MessageChat. ask and said are what you last asked the chat and what its agent last answered.

Send from one chat to another

POST /api/v1/chats/{id}/peers, needs the chats:message scope. Sends a message to another chat in chat {id}'s name, on your behalf. The receiving agent gets it like any peer message, marked as yours, and its answer comes back to {id}, whose agent did not write it. Use Send a message instead to instruct a chat in its own conversation.

curl -X POST https://n8v.online/api/v1/chats/6f1c…/peers \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"to": "9a2e…", "message": "Share the webhook secret name with the checkout."}'

Answers 202:

{
  "id": "pm-7",
  "from": { "id": "6f1c…", "url": "https://n8v.online/task/6f1c…" },
  "to": {
    "id": "9a2e…",
    "name": "API: payments service",
    "status": "running",
    "url": "https://n8v.online/task/9a2e…"
  },
  "state": "pending",
  "route": "live",
  "arrives": "between its steps, within seconds",
  "by": "person",
  "conversation": "pm-7",
  "depth": 0,
  "replayed": false
}

Both chats must be within reach, so the answer can come back. The peer limits per chat, per pair and on wakes apply; how long an exchange goes is yours to decide, so the depth limit does not.

Connect two chats

POST /api/v1/peers/connect, needs the chats:message scope. Introduces two chats to each other so their agents coordinate directly: it turns agent-to-agent messaging on for exactly these two, then each receives one message naming the other, with your brief, and can then read the other with ReadChat and message it with MessageChat.

{
  "chats": ["6f1c…", "9a2e…"],
  "brief": "Agree on the webhook payload before either branch merges."
}

brief is optional, up to 4,000 characters. Both chats are checked before either message goes. Answers 202 with connected: true and both messages in the shape above (the first to the second chat, the second back). If a limit refuses the second message, the first stands and the answer is 207 with connected: false and refused (code, message); retry with the same Idempotency-Key to send only what is missing.

Why a chat waits, and its queue

GET /api/v1/chats/{id}/queue, needs the chats:read scope. Answers 200 with id, url, waiting and messages.

waiting is null when nothing waits. Otherwise it says why, in text (one plain line) and in fields:

position is 1 for next in line, seat is true when a Founding seat's limit applies, until is an ISO time, and messages counts the queued messages. A subscription is named like Claude Max 20x, never by its email.

messages lists the queued messages in the order they run, each with id, text, images, files, model (the model it will run on) and modelSource: message when the message chose it, chat when it takes the chat's model. Messages of one agent run together, on the latest model they name.

Each needs the chats:message scope and answers 200 with the queue as it now is. A message that already ran or was removed answers 404 queue_item_not_found; once the agent took the queue, 409 queue_started; an order that does not name exactly the current queue, 409 queue_changed: read it again and resend.

Fork or restart a chat

POST /api/v1/chats/{id}/fork and POST /api/v1/chats/{id}/restart, need the chats:create scope. Both start a new chat on the same repository from the chat's first message and a summary of its work, linked both ways.

• Fork: a new branch from the chat's latest checkpoint. The chat goes on.
• Restart: the same branch, so the same pull request, on a fresh agent environment; for a chat whose agent environment broke. The chat is stopped and archived.

Answers 202 with id, url, parent, mode, from, repo, branch (null: a new one, named at its first checkpoint), baseBranch, model, archived and status. It counts toward the chats you can start per hour, like starting a chat, and takes an Idempotency-Key.

Repositories

GET /api/v1/repos with chats:create lists the repositories your key can start chats on: repos, each with full_name and default_branch. A key limited to some repositories sees only those. Add ?refresh=true to scan GitHub again instead of the list n8v keeps for ten minutes.

To read a repository without starting a chat, a key with files:read gets its overview, tree, files, commits, branches, tags and pull requests under GET /api/v1/repos/{owner}/{repo}. Read-only, cached and rate limited; environment files, keys and credentials are never returned. See What an assistant can read.

Create repositories

POST /api/v1/repos with chats:create creates one to 20 GitHub repositories in one call, as you: in your own account, or in an organization the n8v GitHub App is installed on. It is off until the Create GitHub repositories feature is on for your account; until then it answers 403 repo_creation_off.

curl -X POST https://n8v.online/api/v1/repos \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Idempotency-Key: new-services-1" \
  -H "Content-Type: application/json" \
  -d '{"repos":[{"name":"billing-api"},{"owner":"acme","name":"billing-web","visibility":"public","description":"Billing front end","default_branch":"trunk"}]}'

Each repository takes:

Nothing is created when the request is wrong: a malformed field, the same repository twice, default_branch without readme (400 invalid_request, with param such as repos[1].name), or an owner n8v cannot reach (403 owner_not_allowed, naming the owners you can use).

Otherwise each repository answers for itself, in order. 201 when every one was created, 207 when some were, and when none was, the first failure's status with its error. The body always holds repos, created and failed:

{
  "repos": [
    { "owner": "ramy", "name": "billing-api", "full_name": "ramy/billing-api", "status": "created", "url": "https://github.com/ramy/billing-api", "visibility": "private", "default_branch": "main", "ready": true },
    { "owner": "acme", "name": "billing-web", "full_name": "acme/billing-web", "status": "failed", "error": { "code": "name_taken", "status": 409, "message": "acme/billing-web already exists on GitHub. Choose another name." } }
  ],
  "created": 1,
  "failed": 1
}

ready says whether a chat can start on it now: a created repository is in GET /api/v1/repos and list_repos at once. When the n8v GitHub App is installed on selected repositories only, ready is false and warning says to give the app access to it.

An app_permission_missing error carries reason and url:

A key limited to some repositories cannot create any (403 repo_not_allowed): a new one would be outside its list. With an Idempotency-Key, a retry answers what the first call did and creates nothing again. Over MCP, create_repos takes the same repos, and idempotency_key.

Repository instructions

Being rolled out. What every agent on a repository is told: standing instructions lead the first message of every new chat, Fast Forward instructions follow your saved prompt on every Fast-Forward. See Repository instructions for which text is in force and what the agent finds in its environment. While they are off for the account, every call here answers 403 instructions_off.

A read answers 200 with scope (account, repo or chat), standing and fastForward (each with text, version, updatedAt, updatedBy, via, max and a waiting proposal or null), effective (per text the text in force and where it is from, or null), fastForwardMessage (what a Fast-Forward would send there, with nothing added by the call), and file and env, where the agent reads the texts. The account has no fastForward: its continuationMessage is that text. ?history=standing or ?history=fastForward adds history, that text's versions newest first, each with version, text, state (live, proposed, accepted or dismissed), at, by and via.

A PATCH takes standing and fastForward, each a Markdown text, or null to clear it so the level inherits; send only what should change. Limits: 8,000 characters for standing, 4,000 for fastForward. With "propose": true nothing changes: the text waits as a proposal you confirm or dismiss in the app. It answers as a read does, plus changed and, for a proposal, proposed: the texts that changed. Setting the same text again changes nothing and makes no version, so a retry is safe. Everything is checked before anything is saved.

curl -sS -X PATCH "https://n8v.online/api/v1/repos/acme/shop/instructions" \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fastForward": "Rebase on main before merging. Merge only on a green gate."}'

A chat's own override is set with Change a chat's settings; the composed message is read with a dry run of Fast-forward a chat. Over MCP: get_instructions, set_instructions, update_chat with instructions, and fast_forward with dry_run.

The n8v primer

Being rolled out. What this account has in n8v, what it can have switched on, what needs something from you first, what is coming, and how to ask: one Markdown text, at most 1,500 words, written from the feature catalog and the account's own switches. It names no internal switch and nothing about other accounts. It is reference for an assistant, not instructions: your own words come first.

Answers 200 with version and primer, or 404 not_found while the primer is off for the account. Over MCP the same text comes once with session_start and with a client's first call of each version, after that call's own answer, and n8v_primer reads it again. A new chat's agent finds it as ~/.n8v/primer.md. Each read and each time it is given is in the activity log, with its version.

Walkthrough

Where the account is in the first-open walkthrough, and starting it again. Answers 403 walkthrough_off while the walkthrough is not on for the account.

GET /api/v1/walkthrough, needs chats:read. DELETE /api/v1/walkthrough, needs chats:message: the walkthrough opens again from the first chapter at the next desktop visit; what was asked for stays asked. Both answer the progress:

curl -sS -X DELETE "https://n8v.online/api/v1/walkthrough" \
  -H "Authorization: Bearer $N8V_API_KEY"

MCP: get_walkthrough, reset_walkthrough.

First task

Early access. A first task before GitHub: for an account without GitHub, a chat without a repository that runs one instruction on Gemini on n8v credits, within fixed limits. Answers 403 trial_off while it is not on for the account.

GET /api/v1/trial, needs chats:read: the trial, the instruction n8v offers (prompt) and its limits. POST /api/v1/trial, needs chats:create, with an optional text (up to 2,000 characters; without it, the offered instruction): 201 with the chat's id, chatId, model and the trial, or 409 trial_refused with the reason (one is running, the tasks or credit are used, the trial has ended, or GitHub is already connected).

MCP: get_trial, start_trial.

Guide

The Guide: every feature by area, one feature, the hints the account's state calls for, and putting one away. Answers 403 guide_off while the Guide is not on for the account. Each read takes lang (en or nl, default en).

A feature has id, area, step (one, parallel, team, setup, beyond, or null when it serves every step), title, what, when, how, founder (text and said, or null), on, ask (off and can be asked for), needs and try (a path in the app, or null). A hint has id, feat, title, why (the fact it rests on), do, try (label, href), more, founder and off.

curl -sS "https://n8v.online/api/v1/guide?q=run%20two%20things%20at%20once" \
  -H "Authorization: Bearer $N8V_API_KEY"

MCP: list_features, get_feature, get_hints, dismiss_hint, ask_for_feature.

Session pulse

Being rolled out. How strongly the account runs today, in five levels, and the thresholds and phrases behind it. See Session pulse. Answers 403 pulse_off while the pulse is not on for the account.

GET /api/v1/session-pulse, needs chats:read. PATCH, needs chats:message: changes only the parts sent, checks the whole and answers 400 invalid_request with the reason when it does not hold. DELETE, needs chats:message: back to the defaults. Every change is in the audit log (kind pulse). All three take ?timezone= (IANA, default UTC; where today starts) and ?lang= (nl or en, used unless a language is stored) and answer the pulse:

th holds four rising steps per signal, the value from which levels 2 to 5 hold; tokens steps are multiples of the typical day. ph holds five levels, each { "nl": [...], "en": [...] }, up to 12 phrases of 80 characters, at least one per level. A PATCH body takes th (any of its three), ph (all five levels) and lang (null for the browser's).

curl -sS -X PATCH "https://n8v.online/api/v1/session-pulse?timezone=Europe/Amsterdam" \
  -H "Authorization: Bearer $N8V_API_KEY" -H "Content-Type: application/json" \
  -d '{"th":{"tasks":[2,4,6,9]},"lang":"nl"}'

MCP: get_session_pulse, set_session_pulse (with reset: true for the defaults).

List models

GET /api/v1/models, no scope needed. Answers 200 with default, the model a chat runs when no model is sent, and models: every model with its id, name, agent, provider, enabled (whether your account's flags let it run) and needs ("chatgpt" when a ChatGPT sign-in must come first, otherwise null). See Model access for how access is decided.

With ?detail=capabilities each model also carries capabilities: per aspect a score, its 0 to 100 normalized value and exact, or null where no source measured the model. aspects names each aspect's source and date. Needs model capabilities to be on for the account; otherwise 403 model_capabilities_off.

Model capabilities

Being rolled out. What each model is strong at, and which to hand a kind of work to. Capabilities need no scope; the recommendation reads quota and needs chats:read. See Model capabilities for the sources and how to read a score.

GET /api/v1/model-capabilities answers with aspects (per aspect its source, metric, unit, source_date, fetched_at and fresh, or null when no source has data), models (one entry per model with its ids and, per aspect, score, normalized, rank, of, source, source_date, fresh, measured_as, exact and the model id to run it with, or null) and sources (each source's last read and last error). Query: aspect (one or more of coding, agentic, reasoning, creative, video, context, speed, cost, comma separated), provider (anthropic, openai, google, xai, opencode, amp) and include_disabled=true.

GET /api/v1/model-capabilities/recommend?intent=coding answers with picks, best first, among the models your account can run: each has the model id, its score and normalized value, measured_as, cost, quota (state is room, limited or unknown, with left_pct and until; null when quota does not apply or is off) and a reason in one sentence. intent is one of coding, agentic, reasoning, creative, video, cheap, fast. Optional: provider, max_cost (USD per 1M tokens, blended 3 input to 1 output) and limit (1 to 20, default 5). left_out names measured models that were excluded and why; no_data names models no source measured. A subscription at its limit ranks last.

curl -sS "https://n8v.online/api/v1/model-capabilities/recommend?intent=coding&provider=anthropic" \
  -H "Authorization: Bearer $N8V_API_KEY"

Over MCP: model_capabilities, recommend_model, and list_models with detail: "capabilities".

Automations

With a key that has automations:read or automations:write, /api/v1/automations lists, reads, creates, changes, pauses, resumes, runs and deletes your automations, and lists their runs with why each failed. Every answer says whether the automation's model can still run, and a model the account cannot run is refused on write and on run with 422 model_unavailable. The key's repositories bound which automations it sees and changes. See Automations API for the calls, the automation object and its errors.

Manage organizations

For people with organizations. These endpoints set organizations up: what Organizations does in its Settings, on an agent's sheet and on Goals and Routines. Reads need organizations:read; every change needs organizations:manage (Manage organizations), a scope of its own because hiring and raising budgets let agents spend more. Your role in the organization still applies: caps, an agent's repository and its connectors are the owner's; the rest is the owner's and admins'. {org} is an organization's key, such as IMM, or its id; {agent} an agent's name (any case) or id.

curl -sS -X POST "https://n8v.online/api/v1/organizations/IMM/agents" \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tax-adviser-1" \
  -d '{"name":"Tax adviser","role":"finance","instructions":"Prepare the quarterly VAT return.","monthly_cap_cents":5000}'

Creates answer 201 and take an Idempotency-Key. Everything is in your activity log. Switch it off for your account under Settings, API, Managing organizations: off, these answer 403 management_disabled.

Artifacts

In early access, behind the flag artifacts. These endpoints do what the Artifacts page and the artifact_* tools do, through the same rules: publish a page or a small package, list and read what was published, compare two versions, share and archive. Reads need artifacts:read (Read artifacts), every change artifacts:write (Publish artifacts). A key sees your own artifacts and those shared with your organizations, and changes only your own. {id} is an artifact's id.

A publish takes these fields. Any other field is refused.

A version holds at most 100 files, 10 MB a file and 25 MB in all, and its file types come from the extension. See What a version may hold. A publish request may be up to 4.4 MB, so that 3 MB of files sent inline fit as base64; larger files go in by reference (file), so their bytes are sent once. Every other request keeps the 256 KB limit.

curl -sS -X POST "https://n8v.online/api/v1/artifacts" \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: churn-report-1" \
  -d '{"title":"Q3 churn report","files":[{"path":"index.html","text":"<!doctype html><title>Churn</title><h1>Churn, Q3</h1>"}]}'

{
  "artifact": {
    "id": "5f0c…",
    "title": "Q3 churn report",
    "kind": "html",
    "visibility": "private",
    "organization": null,
    "repo": null,
    "source": "api",
    "version": 1,
    "files": 1,
    "bytes": 53,
    "archived": false,
    "thumb": false,
    "mine": true,
    "created_at": "2026-11-10T09:12:00.000Z",
    "updated_at": "2026-11-10T09:12:00.000Z",
    "url": "https://n8v.online/artifacts/5f0c…"
  },
  "version": {
    "n": 1,
    "at": "2026-11-10T09:12:00.000Z",
    "by": "Mara",
    "source": "api",
    "from": "CI",
    "note": null,
    "entry": "index.html",
    "files": 1,
    "bytes": 53,
    "chat_id": null,
    "thumb": false
  },
  "unchanged": false,
  "view_url": "https://usercontent.n8v.nl/v1.…/"
}

Every call that answers an artifact answers it in this shape. kind is html for one file and package for several. source says where the latest version came from; version, files and bytes describe that version. thumb says whether its picture is ready, and mine whether the artifact is yours. organization is {id, name} or null. In a version, by is the name of who published it, from the key, app, chat or agent in words, and chat_id the chat whose agent published it.