Core Concepts

Before you start building with the Chatsby API, you need to understand how resources are organized. This guide covers every resource type, their fields, relationships, lifecycle states, and the conventions the API uses for identifiers, timestamps, and idempotency.

Resource Hierarchy

The Chatsby data model follows a clear hierarchy. Every resource belongs to an Account, and resources relate to each other in a predictable tree structure:

Account
├── Agent
│   ├── Source (knowledge base content)
│   ├── Source
│   └── Conversation
│       ├── Message (user)
│       ├── Message (assistant)
│       └── Message (user)
├── Agent
│   ├── Source
│   └── Conversation
│       └── Message
└── Webhook Endpoint (account-level)

The key relationships:

• An Account owns multiple Agents.
• An Agent has multiple Sources (its knowledge base) and multiple Conversations (user interactions).
• A Conversation contains an ordered sequence of Messages.
• Webhook Endpoints are configured at the account level and fire events for all agents.

Agent Resource

An Agent is the central resource in Chatsby. It represents a configured AI chatbot with a specific personality, knowledge base, and behavioral parameters. Every conversation and source belongs to exactly one agent.

Agent Object

Example Agent Object

{
  "id": "agent_1a2b3c4d5e",
  "name": "Customer Support Bot",
  "model": "gpt-4o",
  "system_prompt": "You are a helpful customer support agent for Acme Corp. Be concise and professional. If you don't know the answer, say so honestly.",
  "temperature": 0.5,
  "max_tokens": 1024,
  "status": "active",
  "created_at": "2025-03-10T08:00:00Z",
  "updated_at": "2025-03-12T14:30:00Z"
}

Source Resource

A Source represents a piece of knowledge that an agent can use to answer questions. Sources are processed and indexed when created so the agent can retrieve relevant content at query time.

Source Object

Example Source Object

{
  "id": "src_abc123defg",
  "type": "website",
  "content": "https://acmecorp.com/help",
  "status": "trained",
  "character_count": 24580,
  "agent_id": "agent_1a2b3c4d5e",
  "created_at": "2025-03-10T08:15:00Z"
}

Source Types

Each source type has specific behavior:

Conversation Resource

A Conversation represents an interaction session between an end user and an agent. It is created when the first message is sent and accumulates messages over its lifetime.

Conversation Object

Example Conversation Object

{
  "id": "conv_xyz789abcd",
  "agent_id": "agent_1a2b3c4d5e",
  "metadata": {
    "user_id": "usr_12345",
    "plan": "premium"
  },
  "created_at": "2025-03-15T14:30:00Z",
  "updated_at": "2025-03-15T14:32:00Z",
  "messages": [
    {
      "role": "user",
      "content": "What is your return policy?",
      "timestamp": "2025-03-15T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our return policy allows returns within 30 days of purchase...",
      "sources_used": [
        { "id": "src_abc123defg", "title": "Return Policy Page" }
      ],
      "timestamp": "2025-03-15T14:30:02Z"
    }
  ]
}

Message Resource

A Message is a single exchange within a conversation. Messages are immutable — once created, they cannot be edited or deleted independently.

Message Object

Resource Lifecycle

Resources in Chatsby follow predictable lifecycle patterns:

Agents

create → active → (paused) → deleted

• Active — The agent is ready to receive conversations and respond to messages.
• Paused — The agent exists but does not accept new conversations. Existing conversations remain accessible. Useful for maintenance windows.
• Deleted — The agent and all its associated sources and conversations are permanently removed. This action is irreversible.

Sources

create → pending → processing → trained
                              → failed

• Pending — The source has been submitted but processing has not started.
• Processing — The source is being crawled, extracted, or indexed.
• Trained — Processing is complete and the content is available to the agent.
• Failed — Processing encountered an error. Check the error details and retry.

When a source transitions to trained or failed, a source.trained or source.failed webhook event is fired if you have webhooks configured.

Conversations

create (first message) → active → deleted

Conversations are created implicitly when the first message is sent. They remain active indefinitely until explicitly deleted via the API.

Idempotency

For write operations (POST, PATCH, DELETE), you can include an Idempotency-Key header to safely retry requests without creating duplicate resources.

curl -X POST https://api.chatsby.co/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-abc123" \
  -d '{"name": "Support Bot", "model": "gpt-4o"}'

The idempotency key must be a unique string (UUIDs work well). If you send the same request with the same idempotency key within 24 hours, the API returns the original response instead of creating a duplicate resource. This is essential for safely retrying failed network requests.

Timestamps

All timestamps in the API are in ISO 8601 format and UTC timezone:

2025-03-15T14:30:00Z

The trailing Z indicates UTC. The API does not accept or return timestamps in other timezones. Convert to the user's local timezone in your application layer.

Resource Identifiers

Every resource has a unique identifier with a type prefix for readability:

Identifiers are:

• Globally unique — No two resources of any type share the same ID.
• Immutable — An ID never changes after creation.
• URL-safe — Alphanumeric characters only, safe to use in URL paths.
• Case-sensitive — Always use the exact casing returned by the API.

Relationships Between Resources

Understanding how resources reference each other is important for building correct API queries:

Resources cannot be moved between parents. A source cannot be reassigned to a different agent — you must delete it and create a new one under the target agent.