Zaguán
Enter PassageFounder's Access
Quickstart

Get Started with Orchestrator

Get up and running with Zaguán Orchestrator in minutes. This guide will walk you through authentication, making your first API call, and integrating with your existing code.

Get Started in 5 Minutes

It's literally this simple. Get your API key and make your first request:

curl https://orchestrator.zaguanai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "promptshield/architect",
    "messages": [
      {"role": "user", "content": "Create a Python function to validate emails"}
    ]
  }'

That's it. No complex setup, no configuration files, no infrastructure to manage. Just a simple API call.

Prerequisites

  • A Zaguán account (sign up at zaguanai.com/dashboard)
  • An active API key from your dashboard
  • Basic familiarity with REST APIs or the OpenAI SDK

Step 1: Get Your API Key

Authentication

  1. Log in to your Zaguán Dashboard at zaguanai.com/dashboard
  2. Navigate to the API Keys section
  3. Click "Create New API Key"
  4. Give your key a descriptive name (e.g., "Production Orchestrator")
  5. Copy the API key and store it securely

Important: Store your API key securely. Never commit it to version control or expose it in client-side code.

export ORCHESTRATOR_API_KEY="your-api-key-here"

Step 2: Choose Your Connection Endpoint

Cloudflare-Proxied (Recommended)

https://orchestrator.zaguanai.com/v1
  • •Global CDN with automatic routing
  • •DDoS protection and enhanced security
  • •Automatic SSL/TLS encryption
  • •Best for most use cases

Direct Connection (EU-Finland)

https://orchestrator-eu-fi-01.zaguanai.com/v1
  • •Direct connection to EU datacenter
  • •Lower latency for European users
  • •GDPR-compliant data processing
  • •Best for latency-sensitive EU apps

Step 3: Make Your First Request

Orchestrator is OpenAI-compatible, so you can use the official OpenAI SDKs or any HTTP client. Here are examples in multiple languages:

cURL

curl https://orchestrator.zaguanai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "promptshield/architect",
    "messages": [
      {
        "role": "user",
        "content": "Create a Python function that validates email addresses"
      }
    ]
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://orchestrator.zaguanai.com/v1"
)

response = client.chat.completions.create(
    model="promptshield/architect",
    messages=[
        {"role": "user", "content": "Create a Python function that validates email addresses"}
    ]
)

print(response.choices[0].message.content)

JavaScript/TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://orchestrator.zaguanai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'promptshield/wordsmith',
  messages: [
    { role: 'user', content: 'Write a compelling headline for a SaaS product' }
  ]
});

console.log(response.choices[0].message.content);

Go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    openai "github.com/openai/openai-go"
)

func main() {
    client := openai.NewClient(os.Getenv("ORCHESTRATOR_API_KEY"))
    client.BaseURL = "https://orchestrator.zaguanai.com/v1"

    resp, err := client.Chat.Completions.New(
        context.Background(),
        openai.ChatCompletionNewParams{
            Model: openai.F("promptshield/architect"),
            Messages: openai.F([]openai.ChatCompletionMessageParam{
                openai.ChatCompletionUserMessageParam{
                    Content: openai.F([]openai.ChatCompletionMessageContent{
                        openai.ChatCompletionMessageContentTextParam{
                            Text: openai.F("Create a REST API endpoint for user authentication"),
                        },
                    }),
                },
            }),
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Choices[0].Message.Content[0].Text)
}

Step 4: List Available Personas

Before making requests, you can list all available personas to see what's available:

curl https://orchestrator.zaguanai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns a list of all available personas with their IDs, tiers (standard/fast/pro), and descriptions.

Step 5: Choose Your Tier

Orchestrator offers 4 tiers for different use cases. Select the right tier by appending a suffix to the persona name:

Fast

wordsmith_fast

Speed-optimized. 10-30 seconds. Perfect for drafts and brainstorming.

Standard

wordsmith

Premium quality. 30-60 seconds. Best for professional work.

Pro

wordsmith_pro

Institutional-grade. 60-180 seconds. For complex analysis.

Ultra

counsel_ultra

Mission-critical. 120-300 seconds. Zero-error tolerance.

Tier Selection Example

# Fast tier - quick drafts
model: "promptshield/wordsmith_fast"

# Standard tier - professional work (default)
model: "promptshield/wordsmith"

# Pro tier - deep analysis
model: "promptshield/wordsmith_pro"

# Ultra tier - mission-critical (select personas only)
model: "promptshield/counsel_ultra"

💡 Tip: Start with Standard tier for most work. Use Fast for iteration, Pro for complex tasks, and Ultra for mission-critical work like legal documents or financial models.

Step 6: Enable Streaming (Optional)

Orchestrator supports streaming responses, allowing you to see the AI's thinking process in real-time:

Python (Streaming)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://orchestrator.zaguanai.com/v1"
)

stream = client.chat.completions.create(
    model="promptshield/architect",
    messages=[
        {"role": "user", "content": "Build a user authentication system"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript (Streaming)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://orchestrator.zaguanai.com/v1'
});

const stream = await client.chat.completions.create({
  model: 'promptshield/architect',
  messages: [
    { role: 'user', content: 'Build a user authentication system' }
  ],
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

What's Next?

Now that you've made your first request, explore more features:

  • Browse the Persona Library to find the right expert for your task
  • Read the Best Practices guide to optimize your usage
  • Check out Examples for real-world use cases
  • Review the API Reference for complete endpoint documentation

Need Help?