Nuxa
Feature Inventory

API Reference

REST API endpoints and WebSocket handlers in NUXA Flow

API Reference

NUXA Flow exposes REST APIs for automation and WebSocket handlers for real-time features.


API Overview

DomainEndpointsDescription
Auth10+Authentication and authorization
Workflows15+Workflow CRUD and execution
Copilot10+AI copilot interactions
Voice6+Voice agent APIs
Knowledge5+RAG knowledge base
Files9+File management
Webhooks7+Webhook handling

Authentication

Methods

MethodUse CaseHeader
Session CookieWeb applicationAutomatic
API KeyExternal integrationsx-api-key: <key>
Bearer TokenOAuth flowsAuthorization: Bearer <token>

Getting an API Key

  1. Go to Settings > API Keys
  2. Click Create API Key
  3. Copy and securely store the key
  4. Use in x-api-key header

Core APIs

Auth Endpoints

MethodEndpointDescription
POST/api/auth/loginUser login
POST/api/auth/signupUser registration
POST/api/auth/logoutUser logout
POST/api/auth/reset-passwordPassword reset
GET/api/auth/sessionGet current session
GET/api/auth/callback/[provider]OAuth callback

User Endpoints

MethodEndpointDescription
GET/api/userGet current user
PATCH/api/userUpdate user profile
GET/api/usersList workspace users

Workspace Endpoints

MethodEndpointDescription
GET/api/workspacesList user workspaces
POST/api/workspacesCreate workspace
GET/api/workspaces/[id]Get workspace details
PATCH/api/workspaces/[id]Update workspace
DELETE/api/workspaces/[id]Delete workspace

Workflow APIs

Workflow Management

MethodEndpointDescription
GET/api/workflowsList workflows
POST/api/workflowsCreate workflow
GET/api/workflows/[id]Get workflow
PATCH/api/workflows/[id]Update workflow
DELETE/api/workflows/[id]Delete workflow
POST/api/workflows/[id]/duplicateDuplicate workflow

Workflow Execution

MethodEndpointDescription
POST/api/workflows/[id]/executeExecute workflow
GET/api/workflows/[id]/executionsList executions
GET/api/workflows/[id]/executions/[execId]Get execution details
POST/api/workflows/[id]/executions/[execId]/cancelCancel execution

Workflow Triggers

MethodEndpointDescription
POST/api/webhooks/[workflowId]Webhook trigger
GET/api/webhooks/[workflowId]Webhook trigger (GET)

Copilot APIs

Chat Endpoints

MethodEndpointDescription
POST/api/copilot/chatSend chat message
POST/api/copilot/streamStreaming chat
GET/api/copilot/historyGet chat history
DELETE/api/copilot/historyClear history

Tool Endpoints

MethodEndpointDescription
POST/api/copilot/tools/executeExecute tool
GET/api/copilot/toolsList available tools

Artifact Endpoints

MethodEndpointDescription
GET/api/artifacts/[token]Get artifact
POST/api/artifactsCreate artifact

Voice APIs

Voice Configuration

MethodEndpointDescription
GET/api/voice/configGet voice config
POST/api/voice/configUpdate voice config

Voice Sessions

MethodEndpointDescription
POST/api/voice/sessionCreate voice session
DELETE/api/voice/session/[id]End voice session

Voice Webhooks

MethodEndpointDescription
POST/api/voice/webhook/twilioTwilio webhook
POST/api/voice/webhook/dailyDaily.co webhook

Knowledge Base APIs

Knowledge Management

MethodEndpointDescription
GET/api/knowledgeList knowledge bases
POST/api/knowledgeCreate knowledge base
GET/api/knowledge/[id]Get knowledge base
DELETE/api/knowledge/[id]Delete knowledge base

Document Management

MethodEndpointDescription
POST/api/knowledge/[id]/documentsAdd document
DELETE/api/knowledge/[id]/documents/[docId]Remove document
GET/api/knowledge/[id]/searchSearch knowledge

File APIs

File Operations

MethodEndpointDescription
GET/api/filesList files
POST/api/files/uploadUpload file
GET/api/files/[id]Get file metadata
GET/api/files/[id]/downloadDownload file
DELETE/api/files/[id]Delete file

File Processing

MethodEndpointDescription
POST/api/files/[id]/processProcess file (OCR, etc.)
GET/api/files/[id]/statusGet processing status

Logs APIs

Execution Logs

MethodEndpointDescription
GET/api/logsList execution logs
GET/api/logs/[executionId]Get execution log
GET/api/logs/[executionId]/blocksGet block-level logs

Tool APIs

Tool Execution

MethodEndpointDescription
POST/api/tools/[toolName]Execute tool
GET/api/toolsList available tools

Specific Tools

MethodEndpointDescription
POST/api/tools/gmail/sendSend Gmail
POST/api/tools/slack/messageSend Slack message
POST/api/tools/openai/completeOpenAI completion

Public API (v1)

Versioned API for external integrations.

Base URL

https://app.nuxa.ai/api/v1

Authentication

All v1 endpoints require API key authentication:

curl -H "x-api-key: your_api_key" \
  https://app.nuxa.ai/api/v1/workflows

Endpoints

MethodEndpointDescription
GET/api/v1/workflowsList workflows
POST/api/v1/workflows/[id]/executeExecute workflow
GET/api/v1/executions/[id]Get execution status

WebSocket Handlers

Real-time WebSocket connections for collaborative features.

Connection

import { io } from 'socket.io-client'

const socket = io('wss://app.nuxa.ai', {
  auth: { token: 'your_token' }
})

Socket Handlers

HandlerEventsPurpose
Connectionconnect, disconnectConnection management
Workflowworkflow:join, workflow:updateWorkflow editing
Operationsblock:add, block:update, block:deleteBlock operations
Subblockssubblock:updateSub-block changes
Variablesvariable:set, variable:deleteVariable updates
Presenceuser:join, user:leave, cursor:moveUser presence
YJS Syncyjs:updateCRDT sync
Nova Sonicaudio:start, audio:chunk, audio:endVoice streaming
Chatmessage:new, message:updateChat updates

Workflow Events

// Join workflow room
socket.emit('workflow:join', { workflowId: 'wf_123' })

// Listen for updates
socket.on('workflow:update', (data) => {
  console.log('Workflow updated:', data)
})

// Update block
socket.emit('block:update', {
  workflowId: 'wf_123',
  blockId: 'block_456',
  changes: { name: 'New Name' }
})

Voice Streaming

// Start voice session
socket.emit('audio:start', { sessionId: 'sess_123' })

// Send audio chunk
socket.emit('audio:chunk', {
  sessionId: 'sess_123',
  data: audioBuffer
})

// Receive response
socket.on('audio:response', (data) => {
  playAudio(data.audio)
})

Webhook Handling

Incoming Webhooks

Workflows can receive webhooks at:

POST https://app.nuxa.ai/api/webhooks/[workflowId]

Webhook Payload

{
  "event": "custom_event",
  "data": {
    "key": "value"
  },
  "timestamp": "2024-12-01T00:00:00Z"
}

Webhook Response

{
  "success": true,
  "executionId": "exec_123",
  "result": { ... }
}

Rate Limits

PlanRequests/minConcurrent Executions
Free605
Pro30025
EnterpriseCustomCustom

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699999999

Error Handling

Error Response Format

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "details": { ... }
  }
}

Common Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing authentication
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid request data
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Server error

SDKs

JavaScript/TypeScript

npm install @nuxa/sdk
import { NuxaClient } from '@nuxa/sdk'

const client = new NuxaClient({ apiKey: 'your_key' })

const result = await client.workflows.execute('wf_123', {
  input: { message: 'Hello' }
})

Python

pip install nuxa-sdk
from nuxa import NuxaClient

client = NuxaClient(api_key="your_key")

result = client.workflows.execute("wf_123", {
    "input": {"message": "Hello"}
})

OpenAPI Specification

Full OpenAPI spec available at:

https://app.nuxa.ai/api/openapi.json

Interactive API docs at:

https://app.nuxa.ai/api-docs