---
title: "Add a node to a graph."
method: POST
path: "/graphs/{id}/nodes"
tags: ["graphs"]
---

# Add a node to a graph.

`POST /graphs/{id}/nodes`

## Request

- Base URL: `https://api.livegraph.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.livegraph.ai/graphs/{id}/nodes`
- Auth: one of:
  - API key in cookie `livegraph_session`
  - API key in header `x-api-key`

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `name` string, required
  - `role` 'supervisor' | 'worker' | 'router' | 'reviewer', required
  - `provider` 'anthropic' | 'openai' | 'xai' | 'openrouter' | 'openai-compatible' | 'groq' | 'cerebras' | 'mistral' | 'github-models' | 'nvidia' | 'mock' | 'transform' | 'devin' | 'github-copilot' | 'cursor' | 'cli-agent', required
  - `model` string, required
  - `tier` 'flagship' | 'standard' | 'economy'
  - `systemPrompt` string
  - `description` string
  - `tools` string[]
  - `fileAccessRoot` string, nullable
  - `fallbackChain` object[]
    - `provider` 'anthropic' | 'openai' | 'xai' | 'openrouter' | 'openai-compatible' | 'groq' | 'cerebras' | 'mistral' | 'github-models' | 'nvidia' | 'mock' | 'transform' | 'devin' | 'github-copilot' | 'cursor' | 'cli-agent', required
    - `model` string, required
  - `modelPolicy` 'cheapest', nullable
  - `escalateOn` string[]
  - `maxOutputTokens` integer, nullable
  - `cacheable` boolean, nullable
  - `consensusGroup` object, nullable
    - `edgeIds` string[], required
    - `aggregatorNodeId` string, uuid, required
  - `dispatchTargets` union[]
    - union
      - string, uuid
      - '*'
  - `sshTarget` object, nullable
    - `host` string, required
    - `username` string, required
    - `allowedCommands` object[]
      - `label` string, required
      - `command` string, required
      - `timeoutSeconds` integer
  - `mcpServers` object[], nullable
    - `slug` string, required
    - `url` string, uri, required
    - `allowedTools` string[]
    - `credentialProvider` string
    - `headerName` string, nullable
    - `headers` object
    - `allowedWriteBranches` string[]
  - `httpEndpoints` object[], nullable
    - `slug` string, required
    - `baseUrl` string, uri, required
    - `credentialProvider` string
    - `headerName` string, nullable
    - `credentialHeaders` object
    - `credentialParams` object
    - `headerValuePrefix` string
    - `headerValuePrefixAlt` object
      - `tokenPattern` string, required
      - `prefix` string, required
    - `followRedirects` boolean
    - `redirectScope` 'any' | 'apex-www'
    - `responseFields` string[]
    - `maxOutputBytes` integer
    - `timeoutMs` integer
    - `methods` string[]
    - `risk` 'read' | 'ensure' | 'money' | 'delete'
    - `paths` string[]
    - `allowVaultRefs` boolean
    - `openrouterBatch` boolean
    - `bodyEncoding` 'json' | 'form'
    - `credentialExchange` object
      - `tokenPath` string, required
      - `clientIdField` string
      - `clientSecretField` string
  - `mapConfig` object, nullable
    - `targetNodeId` string, uuid, required
    - `aggregatorNodeId` string, uuid, required
    - `maxConcurrency` integer
    - `maxItems` integer
  - `approvalConfig` object, nullable
    - `instructions` string
    - `notifyWebhookUrl` string, uri
    - `timeoutSeconds` integer
    - `secrets` object
  - `toolApprovalPolicy` object, nullable
    - `gatedTools` string[], required
    - `instructions` string
    - `notifyWebhookUrl` string, uri
    - `timeoutSeconds` integer
  - `toolRiskPolicy` object, nullable
    - `auto` string[]
    - `gated` string[]
    - `instructions` string
    - `notifyWebhookUrl` string, uri
    - `timeoutSeconds` integer
  - `externalAgentConfig` object, nullable
    - `repo` string
    - `baseRef` string
    - `command` string
    - `autoCreatePr` boolean
    - `instructions` string
  - `contextFiles` string[]
  - `position` object, required
    - `x` number, required
    - `y` number, required

## Response `200`

Success — see summary for the response shape.

## Other responses

- `4XX`: Client error — body is the shared {error, code?} envelope.

---

[API](https://skmtc.dev/livegraph/apis/livegraph-api.md) · [All operations](https://skmtc.dev/livegraph/apis/livegraph-api/llms.txt) · [OpenAPI document](https://skmtc.dev/livegraph/apis/livegraph-api/revisions/551085d7719e?raw)