Introduction

The Gnosari API is a FastAPI-based backend for deploying AI agents that run public conversations and extract structured data automatically. The API manages agents, teams, knowledge sources, sessions, billing, and background processing with full async support.

What it does:

• Deploy AI agents via conversational interfaces
• Manage knowledge sources for RAG (Retrieval-Augmented Generation)
• Organize agents into teams for complex workflows
• Persist conversation sessions with automatic summarization
• Extract structured data from conversations
• Handle authentication, access control, and billing

Who it serves:

• Developers building AI-powered applications
• Product teams deploying customer-facing agents
• Data collectors automating structured data extraction

---

Base URL and Versioning

Base URL: /api/v1/

All API endpoints are prefixed with /api/v1/. The version is included in the path to maintain backward compatibility as the API evolves.

Examples:

https://api.gnosari.com/api/v1/agents
https://api.gnosari.com/api/v1/teams
https://api.gnosari.com/api/v1/sessions

Versioning scheme:

• Current version: v1
• Version changes occur when breaking changes are introduced
• Deprecated endpoints are documented with sunset dates

---

Conventions

JSON Request and Response

All requests and responses use JSON format unless otherwise specified.

Request headers:

Content-Type: application/json

Response format:

{
  "id": "resource_id",
  "field": "value",
  "created_at": "2024-01-15T10:30:00Z"
}

UTC Timestamps

All timestamps use ISO 8601 format in UTC:

{
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:00:00Z"
}

Pagination

List endpoints accept PaginationParams and return a PaginatedResponse envelope:

Parameter	Type	Default	Max	Description
skip	integer	0	—	Number of records to skip
limit	integer	50	200	Maximum records to return

Example:

GET /api/v1/agents?skip=0&limit=20

Response envelope:

{
  "data": [...],
  "pagination": {
    "total": 87,
    "skip": 0,
    "limit": 20,
    "has_more": true
  }
}

All list endpoints return this envelope. Access items via response.data; use pagination.has_more to determine whether to fetch more pages.

Response Format

All list and get endpoints return full response objects by default. Use pagination (skip, limit) to manage response sizes for large datasets.

This feature is especially valuable when listing large numbers of resources or when integrating with LLM-based tools that don't need full object details.

Error Handling

Errors return consistent JSON structure:

{
  "detail": "Error message"
}

See Error Codes for complete reference.

---

Authentication

The API supports two authentication methods:

Method	Header	Use Case
JWT Token	Authorization: Bearer <token>	User sessions
API Key	X-AUTH-TOKEN: <api_key>	Server-to-server

Master API Key (internal services only):

X-AUTH-TOKEN: <master_api_key>

For full authentication details, see Authentication.

---

Access Control

Resources (agents, teams, knowledge) support three access levels:

Level	Requirement	Description
PUBLIC	None	Open access
PASSWORD_PROTECTED	X-Access-Password header	Password required
PRIVATE	JWT/API Key + ownership	Account-specific

See Authentication for access control details.

---

Next Steps

• Quick Start: Get your first response in 5 minutes
• Authentication: Learn about authentication methods
• API Reference: Explore resource endpoints in the API section