Skip to content

Responses API Overview

The POST /v1/responses endpoint is the core of the Nodexa API. It accepts a message (or a full conversation history) and returns a response from the configured assistant, optionally streaming tokens in real time.

Endpoint

POST /v1/responses

Base URL: https://your-admin.example.com

Request Headers

Header Required Description
x-api-key Yes (or Authorization) Your Nodexa API key (nxk_...)
Authorization Yes (or x-api-key) Bearer nxk_... — alternative to x-api-key
Content-Type Yes Must be application/json
x-user-id No Identifier for the end user — enables memory lookup
x-user-tokens No JSON object of {"provider_id": "oauth_token"} for tool OAuth

Request Body

{
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "input": "string or InputMessage[]",
  "stream": false,
  "previous_response_id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "instructions": "Optional system prompt override",
  "tools": []
}

Fields

model (required)

Type: string

The UUID of the Nodexa assistant to invoke. This maps to an assistant configured on your platform. Example:

"model": "asst_01234567-89ab-cdef-0123-456789abcdef"

input (required)

Type: string | InputMessage[]

The user's message or a full array of conversation messages.

Simple string:

"input": "What is the weather like today?"

Array of messages:

"input": [
  { "role": "user", "content": "My name is Alice." },
  { "role": "assistant", "content": "Hello Alice! How can I help you?" },
  { "role": "user", "content": "What is my name?" }
]

Returning tool results:

"input": [
  {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"temperature\": 22, \"unit\": \"celsius\"}"
  }
]

See InputMessage Types below for the full type reference.

stream (optional)

Type: boolean Default: false

Set to true to receive a Server-Sent Events stream. See Streaming for the full SSE event reference.

previous_response_id (optional)

Type: string

The id of a previous response in the same conversation thread. When provided, the platform automatically prepends the conversation history so you don't need to include it in input. Example:

"previous_response_id": "resp_01234567-89ab-cdef-0123-456789abcdef"

See Conversation Threading for details.

instructions (optional)

Type: string

A system-level instruction that overrides or supplements the assistant's default system prompt for this request only. Useful for injecting per-request context such as the current date, user locale, or application state.

"instructions": "The user is accessing the billing section. Today is 2024-11-15. Answer in formal English."

tools (optional)

Type: Tool[]

An array of tool definitions available to the assistant for this request. Passing an explicit tools array (even an empty one) overrides the tools configured on the assistant. Omit the field entirely to use the assistant's configured tools unchanged.

See Tools for all supported tool types.

InputMessage Types

Role-based message

{
  "role": "user" | "assistant" | "system",
  "content": "string"
}
Field Type Description
role "user" \| "assistant" \| "system" The author of this message
content string The text content of the message

Function call output

Used to return the result of a client-side tool call to the assistant:

{
  "type": "function_call_output",
  "call_id": "call_abc123",
  "output": "string (JSON-encoded result)"
}
Field Type Description
type "function_call_output" Identifies this as a tool result
call_id string The call_id from the function_call_arguments.done event
output string The tool's return value, JSON-encoded as a string

See Function Calling for the complete flow.

Response Body (non-streaming)

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "object": "response",
  "status": "completed",
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "output": [...],
  "output_text": "The assistant's reply as plain text",
  "created_at": 1700000000
}

Response Fields

Field Type Description
id string Unique response identifier — save for conversation threading
object string Always "response"
status string "completed" or "requires_action"
model string The assistant UUID that handled the request
output OutputItem[] Structured array of output items
output_text string Convenience field — concatenated text from all message items
created_at number Unix timestamp of response creation

status Values

"completed" — The assistant finished processing and all output is present. No further action needed.

"requires_action" — The assistant invoked one or more client-side function tools and is waiting for results. You must execute the functions and send a follow-up request. See Function Calling.

Output Item Types

The output array contains one or more items. The most common types:

Message item:

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "Here is your answer..."
    }
  ]
}

Function call item (when status is requires_action):

{
  "type": "function_call",
  "name": "get_weather",
  "call_id": "call_abc123",
  "arguments": "{\"location\": \"San Francisco\", \"unit\": \"celsius\"}"
}

Reasoning summary item (for reasoning models):

{
  "type": "reasoning",
  "summary": [
    {
      "type": "summary_text",
      "text": "The user is asking about..."
    }
  ]
}

Complete Request/Response Example

Request

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
    "input": "What is the capital of France?",
    "stream": false
  }'

Response

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "object": "response",
  "status": "completed",
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "output_text": "The capital of France is Paris.",
  "created_at": 1700000000
}

Using the OpenAI SDK

Because the Nodexa Responses API is wire-compatible with OpenAI, you can use the official SDK:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://your-admin.example.com/v1',
  apiKey: 'YOUR_API_KEY',
});

// Non-streaming
const response = await client.responses.create({
  model: 'YOUR_ASSISTANT_ID',
  input: 'What is the capital of France?',
});

console.log(response.output_text);
// => "The capital of France is Paris."

console.log(response.id);
// => "resp_01234567-89ab-cdef-0123-456789abcdef"

from openai import OpenAI

client = OpenAI(
    base_url="https://your-admin.example.com/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="YOUR_ASSISTANT_ID",
    input="What is the capital of France?",
)

print(response.output_text)
# => "The capital of France is Paris."