Overview Nadoo AI provides an OpenAI-compatible Chat Completion API . You can integrate with any existing OpenAI SDK or HTTP client — the AI model, workflow, and knowledge base configured for each application are applied automatically.
POST https://your-domain.com/api/v1/chat/{application_id}/chat/completions
application_id can be either an app UUID or an Access Token (for public URLs).
Chat Completion API Uses the same request/response format as OpenAI’s /v1/chat/completions.
Request curl -X POST https://your-domain.com/api/v1/chat/{application_id}/chat/completions \ -H "Authorization: Bearer {your-jwt-token}" \ -H "Content-Type: application/json" \ -H "X-Session-Id: session-abc123" \ -d '{ "model": "gpt-4o", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], "stream": false, "temperature": 0.7, "max_tokens": 1000 }'
Request Body Parameter Type Default Description modelstring"gpt-3.5-turbo"Model ID (overridden by app config) messagesarrayrequired Array of conversation messages streambooleanfalseEnable SSE streaming temperaturefloat0.7Generation temperature (0-2) top_pfloat1.0Nucleus sampling (0-1) max_tokensintegernullMaximum tokens to generate stoparraynullStop sequences toolsarraynullFunction calling tool definitions tool_choicestring/objectnullTool selection strategy metadataobjectnullRequest metadata
Text
Multimodal (Image)
Audio
File Attachments
{ "role" : "user" , "content" : "What's the weather in Seoul?" }
{ "role" : "user" , "content" : [ { "type" : "text" , "text" : "What do you see in this image?" }, { "type" : "image_url" , "image_url" : { "url" : "https://example.com/photo.jpg" , "detail" : "auto" } } ] }
{ "role" : "user" , "content" : [ { "type" : "input_audio" , "input_audio" : { "data" : "base64-encoded-audio..." , "format" : "wav" } } ] }
{ "role" : "user" , "content" : "Summarize this document" , "attachments" : [ { "filename" : "report.pdf" , "fileType" : "pdf" , "size" : 102400 , "uploadedAt" : "2025-03-01T12:00:00Z" } ] }
Response (Non-streaming) { "id" : "chatcmpl-abc123" , "object" : "chat.completion" , "created" : 1709312000 , "model" : "gpt-4o" , "choices" : [ { "index" : 0 , "message" : { "role" : "assistant" , "content" : "Hello! How can I help you?" }, "finish_reason" : "stop" } ], "usage" : { "prompt_tokens" : 25 , "completion_tokens" : 15 , "total_tokens" : 40 } }
Response (Streaming) When "stream": true, tokens are delivered in real time via Server-Sent Events :
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709312000,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]} data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709312000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]} data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709312000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]} data: [DONE]
For Workflow apps, additional SSE events (node execution status, agent reasoning steps, etc.) are emitted during streaming. See SSE Events for details. Authentication Method Header Use Case JWT Bearer Authorization: Bearer {token}Authenticated users API Key X-API-Key: {key}Server-to-server integration Access Token Included in URL path Public chatbot URLs
JWT Bearer
API Key
Access Token (Public)
curl -X POST /api/v1/chat/{app_id}/chat/completions \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
curl -X POST /api/v1/chat/{app_id}/chat/completions \ -H "X-API-Key: nai-your-api-key"
# Use access_token in place of application_id curl -X POST /api/v1/chat/{access_token}/chat/completions
Access Tokens are generated in the app settings and allow unauthenticated public access. See Authentication for full details.
Client Integration Fully compatible with the OpenAI SDK — just change the base_url.
Python (OpenAI SDK)
JavaScript (fetch)
cURL
from openai import OpenAI client = OpenAI( api_key = "nai-your-api-key" , base_url = "https://your-domain.com/api/v1/chat/ {app_id} " ) response = client.chat.completions.create( model = "gpt-4o" , messages = [ { "role" : "user" , "content" : "Hello!" } ], stream = True ) for chunk in response: if chunk.choices[ 0 ].delta.content: print (chunk.choices[ 0 ].delta.content, end = "" )
const response = await fetch ( 'https://your-domain.com/api/v1/chat/{app_id}/chat/completions' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' , 'X-API-Key' : 'nai-your-api-key' , 'X-Session-Id' : 'session-abc123' }, body: JSON . stringify ({ model: 'gpt-4o' , messages: [{ role: 'user' , content: 'Hello!' }], stream: false }) } ); const data = await response . json (); console . log ( data . choices [ 0 ]. message . content );
curl -X POST https://your-domain.com/api/v1/chat/{app_id}/chat/completions \ -H "Content-Type: application/json" \ -H "X-API-Key: nai-your-api-key" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "Hello!"}], "stream": false }'
Behavior by App Type The same Chat Completion endpoint is used for all app types, but the internal processing differs:
Conversations are handled directly by the configured AI model. If a knowledge base is linked, RAG is applied automatically.
Based on system prompt + conversation history
Linked tools/plugins are activated automatically
Supports multimodal input (images, audio, files)
Messages are routed into the workflow graph and processed through the node chain.
Start node → AI Agent → Condition → Search Knowledge, etc.
Node execution status SSE events are emitted during streaming
Use start_node_inputs to pass custom field values to the start node
{ "messages" : [{ "role" : "user" , "content" : "Generate a report" }], "stream" : true , "start_node_inputs" : { "report_type" : "monthly" , "department" : "engineering" } }
Apps connected to external messaging channels (Slack, Discord, etc.). Typically invoked automatically via channel webhooks, but can also be called directly via the Chat Completion API.
Session Management Use the X-Session-Id header to maintain conversation context. Sending the same session ID preserves the conversation history across requests.
# Same session ID across requests → conversation history is maintained curl -X POST /api/v1/chat/{app_id}/chat/completions \ -H "X-Session-Id: user-123-conv-1" \ -d '{"messages": [{"role": "user", "content": "First question"}]}' curl -X POST /api/v1/chat/{app_id}/chat/completions \ -H "X-Session-Id: user-123-conv-1" \ -d '{"messages": [{"role": "user", "content": "Follow-up question"}]}'
Rate Limits Scope Limit Chat Completion 20 requests/min (burst: 5) IP-based (global) 300 requests/min User-based (authenticated) 600 requests/min
Rate-limited responses return HTTP 429 with a Retry-After header.
Management API (Internal) The internal REST API used for platform management is available via FastAPI’s Swagger UI . This API is consumed by the frontend. For external integrations, use the Chat Completion API above.
Swagger UI Available in development mode when DEBUG=true. Browse and test all endpoints.
ReDoc Human-readable API documentation with schemas and examples.
Swagger UI is only enabled when DEBUG=true. It is disabled in production for security.
Authentication JWT, API Key, and Cookie authentication details
SSE Events 19 real-time streaming event types
Error Handling Error codes and response format
