---
title: "POST /agent-playground/graphs/{id}/versions/{version_id}/nodes/"
method: POST
path: "/agent-playground/graphs/{id}/versions/{version_id}/nodes/"
tags: ["agent-playground"]
---

# POST /agent-playground/graphs/{id}/versions/{version_id}/nodes/

`POST /agent-playground/graphs/{id}/versions/{version_id}/nodes/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/agent-playground/graphs/{id}/versions/{version_id}/nodes/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

POST /graphs/{pk}/versions/{version_id}/nodes/

## Request body

- CreateNode
  - `id` string, uuid, required: FE-generated UUID for the node
  - `type` 'subgraph' | 'atomic', required
  - `name` string, required
  - `node_template_id` string, uuid, nullable
  - `ref_graph_version_id` string, uuid, nullable
  - `position` object
  - `source_node_id` string, uuid, nullable
  - `prompt_template` PromptTemplateData, nullable
    - `prompt_template_id` string, uuid, nullable
    - `prompt_version_id` string, uuid, nullable
    - `messages` Message[], required: Array of message objects with id, role, and content array
      - `id` string, required: Unique identifier for the message (frontend-provided)
      - `role` string, required: Message role (e.g., 'system', 'user', 'assistant')
      - `content` MessageContentItem[], required: Array of content items
        - `type` 'text' | 'image_url' | 'audio_url' | 'pdf_url', required: Type of content item
        - `text` string: Text content (required when type=text)
        - `image_url` string, uri: Image URL (required when type=image_url)
        - `audio_url` string, uri: Audio URL (required when type=audio_url)
        - `pdf_url` string, uri: PDF URL (required when type=pdf_url)
    - `response_format` object: String or JSON object.
    - `response_schema` object, nullable: JSON Schema (Draft 7) for structured outputs. Required when response_format='json_schema'. Example: {'type': 'object', 'properties': {...}, 'required': [...]}
    - `model` string, nullable
    - `temperature` number, nullable
    - `max_tokens` integer, nullable
    - `top_p` number, nullable
    - `frequency_penalty` number, nullable
    - `presence_penalty` number, nullable
    - `output_format` string, nullable
    - `tools` object[], nullable
    - `tool_choice` object, nullable
    - `model_detail` object, nullable
    - `variable_names` object, nullable
    - `metadata` object, nullable
    - `commit_message` string, nullable
    - `template_format` string, nullable: Template format: 'mustache' or 'jinja'
    - `save_prompt_version` boolean
  - `ports` PortCreate[]
    - `id` string, uuid, required: FE-generated UUID
    - `key` string, required
    - `display_name` string, required
    - `direction` 'input' | 'output', required
    - `data_schema` object
    - `ref_port_id` string, uuid, nullable
  - `input_mappings` InputMapping[]: List of input mappings from port display_name to source reference
    - `key` string, required: Input port display_name
    - `value` string, nullable: Source reference in format "NodeName.port_display_name" or null

## Response `201`

Created

- CreateNode
  - `id` string, uuid, required: FE-generated UUID for the node
  - `type` 'subgraph' | 'atomic', required
  - `name` string, required
  - `node_template_id` string, uuid, nullable
  - `ref_graph_version_id` string, uuid, nullable
  - `position` object
  - `source_node_id` string, uuid, nullable
  - `prompt_template` PromptTemplateData, nullable
    - `prompt_template_id` string, uuid, nullable
    - `prompt_version_id` string, uuid, nullable
    - `messages` Message[], required: Array of message objects with id, role, and content array
      - `id` string, required: Unique identifier for the message (frontend-provided)
      - `role` string, required: Message role (e.g., 'system', 'user', 'assistant')
      - `content` MessageContentItem[], required: Array of content items
        - `type` 'text' | 'image_url' | 'audio_url' | 'pdf_url', required: Type of content item
        - `text` string: Text content (required when type=text)
        - `image_url` string, uri: Image URL (required when type=image_url)
        - `audio_url` string, uri: Audio URL (required when type=audio_url)
        - `pdf_url` string, uri: PDF URL (required when type=pdf_url)
    - `response_format` object: String or JSON object.
    - `response_schema` object, nullable: JSON Schema (Draft 7) for structured outputs. Required when response_format='json_schema'. Example: {'type': 'object', 'properties': {...}, 'required': [...]}
    - `model` string, nullable
    - `temperature` number, nullable
    - `max_tokens` integer, nullable
    - `top_p` number, nullable
    - `frequency_penalty` number, nullable
    - `presence_penalty` number, nullable
    - `output_format` string, nullable
    - `tools` object[], nullable
    - `tool_choice` object, nullable
    - `model_detail` object, nullable
    - `variable_names` object, nullable
    - `metadata` object, nullable
    - `commit_message` string, nullable
    - `template_format` string, nullable: Template format: 'mustache' or 'jinja'
    - `save_prompt_version` boolean
  - `ports` PortCreate[]
    - `id` string, uuid, required: FE-generated UUID
    - `key` string, required
    - `display_name` string, required
    - `direction` 'input' | 'output', required
    - `data_schema` object
    - `ref_port_id` string, uuid, nullable
  - `input_mappings` InputMapping[]: List of input mappings from port display_name to source reference
    - `key` string, required: Input port display_name
    - `value` string, nullable: Source reference in format "NodeName.port_display_name" or null

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `500`: Internal Server Error
- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)