Gnosari Documentation

Appearance

Quick Start ​

Get started with the Gnosari API in 5 minutes. This guide walks you through authentication, creating an agent, creating a team, and starting a chat session via WebSocket.

Prerequisites ​

  • API running at https://api.gnosari.com (or http://localhost:8001 for local development)
  • Valid user account credentials
  • curl or similar HTTP client
  • WebSocket client (browser, wscat, or similar)

Step 1: Authenticate ​

Obtain a JWT token by logging in:

bash
curl -X POST "https://api.gnosari.com/api/v1/login/access-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=yourpassword"

Response:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Save the access token for use in subsequent requests.

Alternative: API Key Authentication ​

If you have an API key, use it instead:

bash
curl -X GET "https://api.gnosari.com/api/v1/agents" \
  -H "X-AUTH-TOKEN: your-api-key"

API keys are account-specific and can be created in your account settings.

Step 2: Create an Agent ​

Create a simple support agent:

bash
curl -X POST "https://api.gnosari.com/api/v1/agents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Helpful customer support agent",
    "instructions": "You are a friendly customer support agent. Help users with their questions clearly and concisely.",
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "is_orchestrator": true
  }'

Response:

json
{
  "id": 42,
  "identifier": "support-agent",
  "name": "Support Agent",
  "description": "Helpful customer support agent",
  "instructions": "You are a friendly customer support agent...",
  "model": "gpt-4o-mini",
  "temperature": 0.7,
  "is_orchestrator": true,
  "access_level": "PRIVATE",
  "account_id": 1,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Note: The identifier is auto-generated from the name if not provided. Save the identifier for later use.

Step 3: Create a Team ​

Create a team containing your agent:

bash
curl -X POST "https://api.gnosari.com/api/v1/teams" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Team",
    "description": "Customer support team",
    "agent_ids": [42]
  }'

Response:

json
{
  "id": 10,
  "identifier": "support-team",
  "name": "Support Team",
  "description": "Customer support team",
  "agents": [
    {
      "id": 42,
      "name": "Support Agent",
      "identifier": "support-agent"
    }
  ],
  "access_level": "PRIVATE",
  "account_id": 1,
  "created_at": "2024-01-15T10:35:00Z"
}

Save the team identifier for WebSocket connection.

Step 4: Start a Chat Session ​

Connect to the WebSocket endpoint using the team identifier:

WebSocket Connection ​

URL:

wss://api.gnosari.com/ws/chat/support-team?token=YOUR_ACCESS_TOKEN

Using wscat (Node.js WebSocket client):

bash
# Install wscat if needed
npm install -g wscat

# Connect
wscat -c "wss://api.gnosari.com/ws/chat/support-team?token=YOUR_ACCESS_TOKEN"

Send a Message ​

Once connected, send a JSON message:

json
{
  "message": "Hello, can you help me?"
}

Receive Response ​

The agent will respond with streaming events:

json
{"type": "agent_start", "data": {"agent_name": "Support Agent"}}
{"type": "content_delta", "data": {"text": "Hello"}}
{"type": "content_delta", "data": {"text": "! I'd"}}
{"type": "content_delta", "data": {"text": " be happy"}}
{"type": "content_delta", "data": {"text": " to help you."}}
{"type": "content_delta", "data": {"text": " What can I"}}
{"type": "content_delta", "data": {"text": " assist you with?"}}
{"type": "agent_completed", "data": {"final_text": "Hello! I'd be happy to help you. What can I assist you with?"}}

WebSocket Authentication Methods ​

The API supports multiple authentication methods for WebSocket connections:

MethodFormatUse Case
JWT Token?token=<jwt> or Authorization: Bearer <jwt>User sessions
API Key?api_key=<key> or X-AUTH-TOKEN: <key>Server-to-server
Password?password=<password>Password-protected agents

Examples:

# JWT via query parameter
wss://api.gnosari.com/ws/chat/support-team?token=eyJhbGciOi...

# API Key via query parameter
wss://api.gnosari.com/ws/chat/support-team?api_key=your-api-key

# Password-protected agent
wss://api.gnosari.com/ws/chat/public-agent?password=secret123

What's Next? ​

You've successfully:

  • Authenticated with the API
  • Created an agent
  • Created a team
  • Started a chat session via WebSocket

Explore More ​

Development Workflow ​

For iterative development, use pagination to manage response sizes:

bash
# List agents with pagination
curl "https://api.gnosari.com/api/v1/agents?limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get a specific agent
curl "https://api.gnosari.com/api/v1/agents/42" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

See Introduction for response format details.