API Integration

Connect your application to AGO using the SDK API or Public API

AGO provides two APIs for different integration scenarios:

• SDK API (/api/sdk/v1/) — For frontend and mobile apps. Authenticates with a client identifier and validates the request origin. Supports SSE streaming for real-time responses.
• Public API v1 (/api/v1/) — For server-to-server integrations. Authenticates with an API key. Use this when your backend needs to send messages or manage conversations programmatically.

---

Authentication

SDK API (Frontend / Mobile)

Every request to /api/sdk/v1/ requires these headers:

Header	Required	Description
X-User-Anon-Id	Yes	A unique client identifier you generate per device or session
Origin	Yes	Must match one of your allowed domains
Authorization: Bearer {jwt}	No	Optional JWT for authenticated users

const SDK_HEADERS = {
  'X-User-Anon-Id': 'unique-client-id',
};

Public API v1 (Server-to-Server)

Every request to /api/v1/ requires a single header:

Header	Required	Description
X-API-Key	Yes	Your API key (found in admin interface under Administration > API Keys)

const API_HEADERS = {
  'X-API-Key': 'your-api-key',
  'Content-Type': 'application/json',
};

---

SDK API Endpoints

Send Message

POST /api/sdk/v1/messages

Sends a message and returns an SSE streaming response.

Request body:

{
  "content": "How do I reset my password?",
  "conversation_id": "optional-conversation-uuid",
  "agent_id": "optional-agent-uuid",
  "client_functions": [],
  "metadata": {}
}

Only content is required. Omit conversation_id to start a new conversation.

Response: Server-Sent Events stream (see SSE Streaming below).

Get Message Status

GET /api/sdk/v1/messages/{message_id}/status

Poll this endpoint when SSE streaming is not available. Returns the current processing status and any content generated so far.

Submit Feedback

POST /api/sdk/v1/messages/{message_id}/feedback

{
  "rating": "positive"
}

Accepts "positive" or "negative".

List Conversations

GET /api/sdk/v1/conversations

Returns a paginated list of conversations for the current user.

Response:

{
  "items": [...],
  "total": 42,
  "page": 1,
  "page_size": 20
}

Get Conversation

GET /api/sdk/v1/conversations/{conversation_id}

Returns a single conversation with its full message history.

Unread Count

GET /api/sdk/v1/conversations/unread

Returns the number of unread conversations.

Widget Config

GET /api/sdk/v1/config

Returns widget configuration and available forms.

---

Integration Patterns

SSE Streaming (Recommended)

The send-message endpoint returns a Server-Sent Events stream. Each event is a JSON object on a data: line.

async function sendMessage(baseUrl, content, conversationId) {
  const response = await fetch(`${baseUrl}/api/sdk/v1/messages`, {
    method: 'POST',
    headers: {
      ...SDK_HEADERS,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content,
      conversation_id: conversationId || undefined,
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  let fullContent = '';
  let conversationInfo = null;
  let sources = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (!line.startsWith('data: ')) continue;

      const data = JSON.parse(line.slice(6));

      if (data.conversation_id && !conversationInfo) {
        conversationInfo = data.conversation_id;
      }

      if (data.knowledge_sources) {
        sources = data.knowledge_sources;
      }

      if (data.content) {
        fullContent += data.content;
        onContentUpdate(fullContent); // Update UI progressively
      }

      if (data.status === 'DONE') {
        onComplete(fullContent, sources, conversationInfo);
      }
    }
  }

  return { content: fullContent, sources, conversationId: conversationInfo };
}

Polling Fallback

If SSE is blocked by firewalls or proxies, poll the message status endpoint instead:

async function sendMessageWithPolling(baseUrl, content, conversationId) {
  // 1. Send the message
  const sendResponse = await fetch(`${baseUrl}/api/sdk/v1/messages`, {
    method: 'POST',
    headers: {
      ...SDK_HEADERS,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content,
      conversation_id: conversationId || undefined,
    }),
  });

  // Extract message ID from the first SSE event
  const reader = sendResponse.body.getReader();
  const { value } = await reader.read();
  const firstEvent = JSON.parse(new TextDecoder().decode(value).split('data: ')[1]);
  const messageId = firstEvent.message_id;
  reader.cancel();

  // 2. Poll for completion
  let status = 'IN_PROGRESS';
  let result = null;

  while (status === 'IN_PROGRESS') {
    await new Promise((resolve) => setTimeout(resolve, 1000));

    const statusResponse = await fetch(
      `${baseUrl}/api/sdk/v1/messages/${messageId}/status`,
      { headers: SDK_HEADERS }
    );

    result = await statusResponse.json();
    status = result.status;

    if (result.content) {
      onContentUpdate(result.content);
    }
  }

  return result;
}

Conversation Management

Use conversation_id to maintain multi-turn conversations:

class ConversationManager {
  constructor(baseUrl, headers) {
    this.baseUrl = baseUrl;
    this.headers = headers;
  }

  async startConversation(content, agentId) {
    const response = await this.sendMessage(content, null, agentId);
    return response.conversationId;
  }

  async continueConversation(conversationId, content) {
    return this.sendMessage(content, conversationId);
  }

  async listConversations(page = 1) {
    const response = await fetch(
      `${this.baseUrl}/api/sdk/v1/conversations?page=${page}`,
      { headers: this.headers }
    );
    return response.json();
  }

  async getConversation(conversationId) {
    const response = await fetch(
      `${this.baseUrl}/api/sdk/v1/conversations/${conversationId}`,
      { headers: this.headers }
    );
    return response.json();
  }

  async sendMessage(content, conversationId, agentId) {
    // Use the SSE streaming pattern from above
  }
}

---

Public API v1 (Server-to-Server)

Use the Public API when your backend needs to send messages on behalf of users or automate workflows.

Send Message

POST /api/v1/send-message

const fetch = require('node-fetch');

const BASE_URL = 'https://your-ago-instance.com';
const API_KEY = process.env.AGO_API_KEY;

async function sendMessage(content, agentId) {
  const response = await fetch(`${BASE_URL}/api/v1/send-message`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content,
      agent_id: agentId,
    }),
  });

  let fullContent = '';
  let sources = [];

  for await (const chunk of response.body) {
    const text = chunk.toString();
    const lines = text.split('\n').filter((l) => l.startsWith('data: '));

    for (const line of lines) {
      const data = JSON.parse(line.slice(6));
      if (data.knowledge_sources) sources = data.knowledge_sources;
      if (data.content) fullContent += data.content;
    }
  }

  return { answer: fullContent, sources };
}

// Example: answer a support ticket from your backend
async function handleIncomingTicket(ticketContent) {
  const result = await sendMessage(ticketContent, 'your-agent-uuid');
  console.log('Answer:', result.answer);
  return result;
}

---

Best Practices

• Stream responses to users as they arrive. Do not wait for the full response before displaying content.
• Set timeouts to 60+ seconds for streaming connections. AI responses can take time depending on the query.
• Store conversation_id from the first response and pass it back on subsequent messages to maintain context.
• Never expose X-API-Key in frontend code. The Public API is for server-to-server use only. Use the SDK API (X-User-Anon-Id) for frontend apps.
• Implement retry with backoff for transient errors (5xx, network timeouts).

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) {
        await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
        continue;
      }
      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }
}

---

Troubleshooting

Problem	Cause	Fix
401 Unauthorized	Missing or invalid auth headers	Verify X-User-Anon-Id is set correctly. For Public API, check X-API-Key.
403 Forbidden	Origin not in allowed domains	Add your domain to the allowed origins list in admin interface > Channels.
SSE stream disconnects early	Proxy or load balancer timeout	Increase proxy timeout to 60+ seconds, or switch to the polling fallback.
429 Too Many Requests	Rate limit exceeded	Add client-side throttling and retry with exponential backoff.
Empty response body	Stream not fully consumed	Make sure you read until done === true before closing the connection.

---

Related Documentation

• Widget Authentication — Token setup for frontend apps
• API Key Authentication — API key management
• Portal Integration — Full web portal alternative