n8n Integration

Installation

n8n-nodes-antbase

cd ~/.n8n
npm install n8n-nodes-antbase

FROM n8nio/n8n:latest
RUN cd /usr/local/lib/node_modules/n8n && \
    npm install n8n-nodes-antbase

Setup

After installing the node, configure your Antbase credentials in n8n.

Node Operations

The Antbase node exposes three operations. Pick the one that fits your workflow.

Virtual Models

Use virtual models to let Antbase route to the best provider and model for each request.

You can also pass any specific provider model ID (e.g. gpt-4o, claude-sonnet-4-20250514) to bypass routing. See Virtual Models for the full list.

Workflow Examples

// Antbase node configuration (Simple Chat operation)
{
  "model": "ant:fast",
  "system": "Classify the following email into exactly one category: support, sales, billing, spam. Respond with JSON: {"category": "...", "confidence": 0.0}",
  "prompt": "{{ $json.body }}",
  "temperature": 0,
  "response_format": { "type": "json_object" }
}

// Output (piped to a Switch node):
// { "category": "support", "confidence": 0.95 }

// Antbase node configuration (Simple Chat operation)
{
  "model": "ant:auto",
  "system": "Extract invoice fields from the text. Return JSON with: invoice_number, date, vendor, line_items (array of {description, quantity, unit_price, total}), subtotal, tax, grand_total.",
  "prompt": "{{ $json.invoiceText }}",
  "temperature": 0,
  "response_format": { "type": "json_object" }
}

// Output:
// {
//   "invoice_number": "INV-2026-0042",
//   "date": "2026-03-15",
//   "vendor": "Acme Corp",
//   "line_items": [
//     { "description": "Widget A", "quantity": 10, "unit_price": 25.00, "total": 250.00 }
//   ],
//   "subtotal": 250.00,
//   "tax": 20.00,
//   "grand_total": 270.00
// }

// Antbase node configuration (Simple Chat operation)
{
  "model": "ant:best",
  "system": "You are a professional translator. Translate the following text to {{ $json.targetLanguage }}. Preserve formatting and tone. Return only the translation, no commentary.",
  "prompt": "{{ $json.sourceText }}",
  "temperature": 0.3
}

// Workflow structure:
// Trigger -> Set languages ["es","fr","de","ja"]
//   -> Split in Batches
//     -> Antbase (translate)
//   -> Merge -> Save to CMS

Output Schema

The Antbase node returns a standard OpenAI-compatible chat completion object. Access the generated text in subsequent nodes.

// The node outputs the full completion object:
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-2024-08-06",         // actual model used
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The generated response text..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 128,
    "total_tokens": 170
  }
}

// In subsequent nodes, reference:
//   {{ $json.choices[0].message.content }}  -- the response text
//   {{ $json.model }}                       -- which model was actually used
//   {{ $json.usage.total_tokens }}          -- token count

Error Handling

Antbase handles retries and failover automatically, but some errors will surface to n8n. Use n8n's built-in Error Trigger node to catch these.

Self-Hosted Gateway

# In n8n Antbase credential settings:
Base URL: http://antbase.internal:3001/v1

# Or if running n8n and Antbase in the same Docker network:
Base URL: http://orqa-api:3001/v1

All node operations work identically against a self-hosted gateway. You bring your own provider API keys, configured in the gateway's environment.

Tips

• Use ant:fast for triage steps. In multi-step workflows, use a fast model for classification or routing decisions, then escalate to ant:best only when needed. This keeps costs low and latency tight.
• Always set response_format for structured output. When you need to parse the AI response in downstream nodes, force JSON mode. This prevents the model from wrapping its answer in markdown or natural language.
• Set temperature: 0 for deterministic tasks. Classification, extraction, and data transformation should use zero temperature for consistent results across runs.
• Use n8n expressions in prompts. Reference data from previous nodes with {{ $json.fieldName }} to build dynamic prompts without code nodes.
• Monitor usage in the Antbase dashboard. The dashboard shows per-request routing decisions, latency, and cost breakdown -- useful for optimizing which virtual model each workflow step uses.
• Handle errors gracefully. Connect an Error Trigger node to send alerts (Slack, email) when AI steps fail. For critical workflows, add a fallback branch that uses a different model.