OpenAI ChatGPT Responses Call v1

Use this Node to create and manage OpenAI Responses and Conversations.

You can chain Responses and give the model access to function, MCP, and hosted tools.

Revision History

1.0.0.0 Initial release
2.0.0.0 Expanded tool support (function, MCP, and hosted tools: web search, file search, code interpreter, image generation).
2.1.0.0 Added background mode (with RetrieveResponse and CancelResponse operations) and optional initial polling.
2.2.0.0 Added optional Metadata and SafetyIdentifier inputs for create requests (attribution and end-user safety).
2.3.0.0 Preserved message content annotations, including Web Search URL citations, in NormalisedResponse.
2.4.0.0 Added Conversation and deletion operations, Response storage control, paginated Conversation items, and the Response output for all operations.

Properties

Connection

Type: Connection Input

ApiKey
Type: Secret Input
Your OpenAI API key.

Model
Type: String Input
Model ID to use for Responses requests. Default is gpt-5-2025-08-07. For the full, up-to-date model list, see: OpenAI Models.

ReasoningEffort
Type: List Input
Controls reasoning effort for reasoning-capable models.

  • None - Disables additional reasoning effort for fastest responses. Supported on gpt-5.1 and later; earlier models do not support none.
  • Minimal - Very light reasoning; favors speed and lower token use.
  • Low - Light reasoning for simple tasks.
  • Medium - Balanced reasoning quality and latency (default).
  • High - Deeper reasoning for harder tasks; higher latency/token use.
  • XHigh - Maximum reasoning depth; slowest and most expensive. Supported on models after gpt-5.1-codex-max.

Model support varies: gpt-5-pro only supports High, while gpt-5.1 supports None, Low, Medium, and High. OpenAI returns an error when the model does not support your selection.

ReasoningSummary
Type: List Input
Controls reasoning summary verbosity (or omission).

  • None - Do not return a reasoning summary.
  • Auto - Let the model decide summary verbosity.
  • Concise - Short summary only.
  • Detailed - Longer, more explicit summary.

Temperature
Type: Number Input
Sampling temperature, valid range 0.0 to 2.0. Lower values are more deterministic; higher values add randomness and creativity.

TextVerbosity
Type: List Input
Controls verbosity of text responses (output text tokens).

  • Low - Shorter, terse responses.
  • Medium - Balanced verbosity (default).
  • High - More detailed responses.

MaxOutputTokens
Type: Int32 Input
Maximum output tokens. 0 means no cap is sent.

Truncation
Type: List Input
Context overflow behavior.

  • Auto - Truncates input when needed to fit the model context.
  • Disabled - Fails if inputs exceed the model context.

ToolChoice
Type: List Input
Controls whether the model may call tools.

  • None - Do not call tools.
  • Auto - Let the model decide when to call tools.
  • Required - Force at least one tool call.

ParallelToolCalls
Type: Boolean Input
Allows multiple tool calls in a single response.

PromptCacheRetention
Type: List Input
Controls prompt cache retention policy. OpenAI supports in_memory and 24h retention in Responses requests.

  • Auto - Node selects 24h for supported models, otherwise in_memory.
  • InMemory - Short-lived in-memory caching only.
  • Hours24 - Request 24-hour retention where supported.

In-memory retention typically persists for 5-10 minutes of inactivity, up to about one hour.

PromptCacheKey
Type: String Input
Optional override for prompt_cache_key. When blank, the Node derives a stable key from model, instructions, and tools.

Operation

Type: List Input
Selects which operation the Node performs.

  • CreateResponse - Create a new Response (default).
  • RetrieveResponse - Fetch the current state of an existing Response identified by CurrResponseId. Use this to poll a background Response until it reaches a terminal status.
  • CancelResponse - Cancel an in-progress response identified by CurrResponseId. Only responses created with Background enabled can be cancelled.
  • CreateConversation - Create a Conversation.
  • RetrieveConversation - Retrieve the Conversation identified by ConversationId.
  • ListConversationItems - Retrieve items from the Conversation identified by ConversationId.
  • DeleteConversationItem - Delete the item identified by ConversationItemId from the Conversation identified by ConversationId.
  • DeleteConversation - Delete the Conversation identified by ConversationId.
  • DeleteStoredResponse - Delete the stored Response identified by CurrResponseId.

Background

Type: Boolean Input
Applies only to CreateResponse. When enabled, the Node returns the Response id and a non-terminal status (queued or in_progress) without waiting for completion. The default is disabled, so the Node waits for the full Response.

InitialPollTimeoutSecs

Type: Int32 Input
Applies only to a background CreateResponse. A value greater than 0 makes the Node poll about once per second until the Response reaches a terminal status or the timeout elapses. The default value of 0 returns the initial state without polling.

Instructions

Type: Multiline Text Input
System or developer message inserted into the model context.

PrevResponseId

Type: String Input
Applies only to CreateResponse. If set, the Node chains the new Response from a previous Response ID. Leave it blank when you use ConversationId. The Node rejects a request when both values are effective.

CurrResponseId

Type: String Input
The ID of an existing Response to act on. Required for RetrieveResponse, CancelResponse, and DeleteStoredResponse. This differs from PrevResponseId, which chains a new Response from a previous Response.

ConversationId

Type: String Input
The ID of a Conversation. Set it on CreateResponse to add the new Response and its input to that Conversation. It is required for RetrieveConversation, ListConversationItems, DeleteConversationItem, and DeleteConversation. Leave it blank for CreateConversation.

ConversationItemId

Type: String Input
The ID of an item within a Conversation. Required only for DeleteConversationItem.

StoreMode

Type: List Input
Controls Response storage for CreateResponse. This is separate from the prompt-cache retention settings on the Connection.

  • Default - Omit the OpenAI store field.
  • Enabled - Send store as true.
  • Disabled - Send store as false.

Limit

Type: Int32 Input
The maximum number of provider items returned by ListConversationItems. The default is 20, and the valid range is 1 to 100. An explicit value of 0 is invalid. The limit counts all provider items, not only visible messages.

AfterItemId

Type: String Input
An optional item ID used as the pagination cursor for ListConversationItems. Set it to the preceding page's last_id to retrieve another page when has_more is true.

Order

Type: List Input
Controls the item order for ListConversationItems. The default is Desc.

  • Desc - Return newest items first.
  • Asc - Return oldest items first.

Input

Type: Multiline Text Input
User input. The Node accepts plain text or JSON input items.

Metadata

Type: JSON Input
Use this optional JSON object to attach searchable information to a created Response. Include string values only. It applies to CreateResponse.

SafetyIdentifier

Type: String Input
Optional stable, privacy-preserving identifier for the end user. Used by OpenAI to help detect abuse. Sent unchanged only on CreateResponse.

Tools

Type: JSON Input
A JSON array that defines tools the model may call. See Tools Schema for supported types and examples.

Response

Type: JSON Output
The JSON result for all nine operations. The Node validates JSON from OpenAI before writing it to this output. See Deleting Resources for generated deletion acknowledgements.

NormalisedResponse

Type: JSON Output
A smaller JSON view for CreateResponse, RetrieveResponse, and CancelResponse:

{
  "id": "<response id>",
  "status": "<status>",
  "output": []
}

NormalisedResponse.output[].content[] preserves additional fields returned by OpenAI, including annotations. OpenAI can add message content fields without requiring the Node to model each field.

Web Search output can include url_citation entries in the annotations array of an output_text content part:

{
  "type": "output_text",
  "text": "Read the source.",
  "annotations": [
    {
      "type": "url_citation",
      "start_index": 9,
      "end_index": 15,
      "title": "Example source",
      "url": "https://example.com"
    }
  ]
}

When available, error contains the provider error and usage contains token counts. The Node omits fields with null values.

NormalisedResponse is empty for the six resource operations and contains a subset of the provider fields. Use Response for operation results, metadata, raw tool-call details, Conversation resources, pagination fields, and deletion results.

Setting up the Node

1) Create the Connection

  • Go to the Flowgear Console and create a Connection of type OpenAI ChatGPT Responses Call.
  • Set ApiKey and confirm the Model you want to use.
  • Leave PromptCacheKey blank if you want the Node to generate a stable cache key automatically.

2) Configure the Connector Inputs

  • Select Operation and set the required ID or pagination Properties.
  • For CreateResponse, set Input and any optional create Properties you need, such as Instructions, Tools, or Background.
  • Invoke the Node and read the result and resource IDs from Response.

3) Test before Invoke

Use the Connection's Test action to validate its Properties and network access. The test calls GET /models.

Remarks

Input Formats

The Node accepts multiple input styles for Input:

  • Plain text (becomes a single user message).
  • A JSON object representing one input item.
  • A JSON array of input items.
  • A quoted JSON string (treated as plain text).
  • A tool output item with type = function_call_output, plus the call_id from the tool call and your output payload.

If JSON parsing fails, the Node falls back to a single user message using the raw text.

Example: tool output item passed to Input

{
  "type": "function_call_output",
  "call_id": "call_abc123",
  "output": "{\"status\":\"ok\",\"result\":\"42\"}"
}

Metadata and SafetyIdentifier

The Node supports two create-only inputs for attribution and end-user safety:

Metadata

A JSON object containing only string values.

  • Metadata can contain up to 16 entries.
  • Keys can be up to 64 characters and values up to 512 characters.
  • Invalid, non-empty metadata causes the Node call to fail.

Do not store secrets or sensitive personal information in metadata.

Example:

{
  "user_id": "user_456",
  "session_id": "session_789",
  "request_source": "web_widget"
}

SafetyIdentifier

A stable, privacy-preserving identifier for each end-user (for example, safety_abc123). Reuse the same value for that user's create requests.

OpenAI recommends hashing a username or email address instead of sending it directly. Use a stable session ID for anonymous users.

See OpenAI safety best practices.

Background Mode

When you enable Background for CreateResponse, the Node returns before OpenAI finishes the request. Use this pattern:

  1. Set Operation to CreateResponse and enable Background. The Node returns an id and a non-terminal status (queued or in_progress). Read the ID from Response.id or NormalisedResponse.id.
  2. Poll with Operation set to RetrieveResponse, passing the ID as CurrResponseId, until status is terminal (completed, failed, cancelled, or incomplete).
  3. To cancel a running Response, set Operation to CancelResponse and use the same CurrResponseId.

Set InitialPollTimeoutSecs to a small positive value to make the Node poll after creating a background Response. Set it to 0 to return the initial result without polling.

Response Chains and Conversations

Use these IDs for different resources:

  • ConversationId identifies the Conversation to bind a new Response to, retrieve, list, or delete.
  • PrevResponseId identifies the previous Response in a chain. CurrResponseId identifies the Response to retrieve, cancel, or delete.
  • ConversationItemId identifies the item to delete from a Conversation.
  • call_id identifies the function tool call matched by a function_call_output input item.

To chain Responses without a Conversation, leave ConversationId blank. After each CreateResponse invocation, pass the returned Response.id to PrevResponseId on the next invocation.

The six resource operations require a valid ApiKey and their applicable ID or pagination Properties. They ignore generation Properties, including Model, Instructions, Input, Tools, Metadata, SafetyIdentifier, Background, and InitialPollTimeoutSecs.

Create and continue a Conversation

CreateConversation creates an empty Conversation. Send each message once through CreateResponse.

  1. Set Operation to CreateConversation and invoke the Node.
  2. Read the Conversation ID from Response.id. In this example, the returned ID is conv_example123.
  3. Set Operation to CreateResponse, set ConversationId to conv_example123, leave PrevResponseId blank, and enter the first message in Input. Invoke the Node.
  4. Replace Input with the next message and invoke CreateResponse again with the same ConversationId.

List another page of items

Each ListConversationItems invocation returns one page.

  1. Set Operation to ListConversationItems and ConversationId to conv_example123.
  2. Set Limit to 20 and Order to Desc. Leave AfterItemId blank for the first page.
  3. Invoke the Node and read data, first_id, last_id, and has_more from Response.
  4. If has_more is true, set AfterItemId to the returned last_id and invoke the Node again.

Deleting Resources

Check each ID before you invoke a deletion operation. These examples use synthetic IDs:

  • To delete one item from a Conversation, select DeleteConversationItem, set ConversationId to conv_example123, and set ConversationItemId to item_example456.
  • To delete a Conversation while keeping its items, select DeleteConversation and set ConversationId to conv_example123.
  • To delete one stored Response, select DeleteStoredResponse and set CurrResponseId to resp_example789.

For a successful deletion response other than HTTP 204, the Node preserves valid nonempty provider JSON in Response. For an empty HTTP 200 response, or an HTTP 204 response with an empty or valid JSON body, the Node returns this acknowledgement:

{"deleted":true}

The Node fails the invocation when OpenAI returns HTTP 202 because deletion remains unconfirmed. It also fails on HTTP errors, including 404 responses, and malformed JSON results.

Tools Schema

Tools must be a JSON array. Supported tool types:

  • function (custom function calls)
  • mcp (remote MCP servers or OpenAI connectors)
  • web_search (hosted web search)
  • file_search (hosted retrieval over OpenAI vector stores)
  • code_interpreter (hosted code execution)
  • image_generation (hosted image generation)

Function Tool

Example (function tool):

[
  {
    "type": "function",
    "name": "lookupWeather",
    "description": "Returns current weather for a city",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "City name" }
      },
      "required": ["city"],
      "additionalProperties": false
    }
  }
]

Use function tools to let the model call a specific Flowgear action with a structured JSON payload.
OpenAI Documentation: Function Calling

MCP Tool

Example (MCP tool - Remote Server without OAuth):

[
  {
    "type": "mcp",
    "server_label": "flowgear",
    "server_url": "https://mcp.example.com"
  }
]

Use MCP tools to connect the model to external MCP servers and their tool catalog.
OpenAI Documentation: Remote MCP Servers

Example (MCP tool - OpenAI Connector with OAuth token):

[
  {
    "type": "mcp",
    "server_label": "drive",
    "connector_id": "conn_123",
    "authorization": "Bearer <access_token>"
  }
]

Use connector-based MCP tools when OpenAI hosts the integration and an OAuth access token is available.
OpenAI Documentation: Remote MCP Servers

Notes:

  • Remote MCP servers typically use server_url. Any authentication requirements are determined by the MCP server.
  • OpenAI connectors use connector_id and require an OAuth access token in authorization.

MCP Authentication

This Node does not perform OAuth. When you use connector_id, handle the OAuth login and token refresh outside the Node, then pass the access token in authorization.

Use this Flowgear pattern:

  1. Handle the entire implementation of your own MCP client, or perhaps use the OAuthHandler to complete the provider login. The feasibility of this will be very specific to the MCP server you are trying to connect with.
  2. Store the access token securely.
  3. Inject the token into the MCP tool definition in Tools:
[
  {
    "type": "mcp",
    "server_label": "drive",
    "connector_id": "conn_123",
    "authorization": "Bearer <access_token>"
  }
]

If the token is missing or expired, OpenAI returns an authentication error.

Web Search Tool

Use web_search when the response needs current information from the public web.
OpenAI Documentation: Web Search Tool

Example (web_search):

[
  {
    "type": "web_search",
    "filters": { "allowed_domains": ["example.com"] },
    "search_context_size": "medium",
    "user_location": {
      "type": "approximate",
      "country": "US",
      "city": "Seattle",
      "region": "WA",
      "timezone": "America/Los_Angeles"
    }
  }
]

File Search Tool

Use file_search to retrieve relevant passages from OpenAI vector stores.
OpenAI Documentation: File Search Tool

Example (file_search):

[
  {
    "type": "file_search",
    "vector_store_ids": ["vs_123"],
    "max_num_results": 5
  }
]

File Search Setup (OpenAI Vector Stores)

File Search requires an OpenAI vector store that already contains the files you want the model to retrieve. This Node does not create vector stores or upload files automatically.

To set up File Search:

  1. Create a vector store in OpenAI.
  2. Upload one or more files to that vector store.
  3. Wait for the files to finish processing (status must be completed).
  4. Add the vector store ID to your tool definition as vector_store_ids.

OpenAI Documentation:

If results are consistently empty, confirm that the vector store contains files, the file processing status is completed, and the content is searchable (plain text or a supported document type).

Code Interpreter Tool

Use code_interpreter for calculations, data transformation, or running analysis code.
OpenAI Documentation: Code Interpreter Tool

Example (code_interpreter):

[
  {
    "type": "code_interpreter",
    "container": { "type": "auto" }
  }
]

Image Generation Tool

Use image_generation to create images from text prompts or structured instructions.
OpenAI Documentation: Image Generation Tool

Example (image_generation):

[
  {
    "type": "image_generation",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "output_compression": 100,
    "background": "transparent",
    "action": "auto"
  }
]

Learn more about how tool and function calling works: OpenAI Tools and Function Calling Guide

Prompt Caching

Prompt caching is enabled by default. It reuses matching prompt prefixes, so that repeat requests can be faster and cheaper. OpenAI only caches exact prompt prefixes, so keep stable content (instructions, tools, schemas) at the beginning and put dynamic content at the end. Tools must be identical between requests to benefit from caching.

  • PromptCacheRetention controls whether the request uses in_memory or 24h retention.
  • PromptCacheKey can improve cache routing when many requests share the same prefix.
  • Cache hits appear as usage.prompt_tokens_details.cached_tokens (or usage.input_tokens_details.cached_tokens) in the raw response. Cached tokens are only non-zero for prompts at or above 1024 tokens and are reported in 128-token increments.
  • If you leave PromptCacheKey empty, the Node generates a stable key from your selected model, instructions, and tools.

For best results, keep your long, stable instructions and tool definitions consistent across runs, and move user-specific data to the end of the prompt. If you batch many similar requests, set a stable PromptCacheKey derived from the shared prefix so OpenAI can route them efficiently.

Learn more about how prompt caching works: OpenAI Prompt Caching Guide

Streaming

This connector uses non-streaming Responses API calls and waits for the full response before returning. For long-running requests, use Background mode (see Background Mode) instead of waiting synchronously.

Error Handling

  • Non-2xx HTTP responses are raised as Flowgear errors and include the OpenAI error object when possible.
  • For a foreground CreateResponse, a 2xx response that still contains an error object is also treated as an error to avoid silent failures.
  • For background operations (RetrieveResponse, CancelResponse, and a background CreateResponse), a terminal error is surfaced on NormalisedResponse.error instead of being raised, so you can inspect a failed or cancelled response while polling.
  • The Node clears Response and NormalisedResponse when an invocation fails, so the Workflow cannot read stale or unvalidated output. If convenience polling fails after a background create succeeds, the Node keeps the last valid pair from that invocation.

See also