Polmy.ai API Documentation

Welcome to the Polmy.ai API documentation. Our APIs provide programmatic access to knowledge stores, AI agents, and more. This documentation will help you integrate Polmy.ai into your applications.

Try Knowledge Store API Try Agent API

Authentication

All API requests must include an API key for authentication. You can create API keys in your dashboard after signing up.

Authentication Headers

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure! Do not expose them in client-side code or public repositories.

Knowledge Store API

The Knowledge Store API allows you to query your knowledge stores and retrieve relevant information based on natural language queries.

Query Knowledge Store

POST /api/v1/ks/{knowledge_store_id}/query/

Request Body

{
  "query": "What is the pricing structure?",
  "max_results": 5
}

Response

{
  "results": [
    {
      "content": "Our pricing structure has three tiers: Basic, Pro, and Enterprise...",
      "metadata": {
        "source": "pricing.pdf",
        "page": 2
      },
      "relevance_score": 0.92
    },
    ...
  ],
  "query_id": "6f9d7a3e-5b8c-4a7f-b71d-c390a8957849"
}

Agent API

The Agent API allows you to create and manage AI agent conversations through threads, messages, and interventions.

Message Roles

All messages in the agent API include a role field with one of the following values:

human: Messages from the user
assistant: Responses from the AI agent
system: System-level instructions or information
tool: Messages from tools used by the agent
human-intervention: Messages from human operators during an intervention

Client applications should use these roles to determine how to display different message types in the UI.

List Agents

GET /api/v1/agents/

Response

{
  "agents": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Customer Support Agent",
      "description": "Helps with customer inquiries",
      "type": "react",
      "created_at": "2023-01-01T12:00:00Z"
    },
    {
      "id": "8fb95f64-5717-4562-b3fc-2c963f66ccc7",
      "name": "Sales Assistant",
      "description": "Assists with product information",
      "type": "reflexion",
      "created_at": "2023-01-02T10:30:00Z"
    }
  ]
}

Threads

Threads represent conversations with AI agents. You create a thread first, then add messages to it.

Create Thread

POST /api/v1/threads/create/

Request Body

{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "New Thread",
  "external_user_id": "user_123"
}

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "New Thread",
  "created_at": "2023-01-01T12:00:00Z",
  "agent": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Agent Name",
    "type": "react"
  }
}

Delete Thread

DELETE /api/v1/threads/{thread_id}/delete/

Query Parameters

external_user_id - Required: The external identifier of the thread owner

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Thread Title",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "deleted"
}

POST /api/v1/threads/create/

Request Body

{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metadata": {
    "user_id": "user_123",
    "session_id": "session_456"
  }
}

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "active",
  "metadata": {
    "user_id": "user_123",
    "session_id": "session_456"
  }
}

List Threads

GET /api/v1/threads/

Response

{
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z",
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "active",
      "metadata": {
        "user_id": "user_123"
      }
    },
    ...
  ],
  "count": 10,
  "next": null,
  "previous": null
}

Get Thread

GET /api/v1/threads/{thread_id}/

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z",
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "active",
  "metadata": {
    "user_id": "user_123"
  },
  "messages": [
    {
      "id": "msg_123",
      "role": "human",
      "content": "Hello, can you help me?",
      "created_at": "2023-01-01T12:01:00Z"
    },
    {
      "id": "msg_124",
      "role": "assistant",
      "content": "Yes, I'd be happy to help. What do you need?",
      "created_at": "2023-01-01T12:01:10Z"
    }
  ]
}

Messages

Messages are sent to a thread to communicate with an AI agent.

Create Message

POST /api/v1/threads/{thread_id}/messages/

Request Body

{
  "content": "I need help with setting up a knowledge store.",
  "role": "user"
}

Response

{
  "id": "msg_125",
  "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2023-01-01T12:05:00Z",
  "role": "human",
  "content": "I need help with setting up a knowledge store.",
  "status": "delivered"
}

Interventions

Interventions allow human operators to take over or assist AI agents during conversations.

List Interventions

GET /api/v1/threads/{thread_id}/interventions/

Response

{
  "interventions": [
    {
      "id": "int_123",
      "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "approval_required",
      "status": "pending",
      "created_at": "2023-01-01T12:10:00Z",
      "content": {
        "question": "Should I provide pricing information?",
        "context": "The user is asking about enterprise pricing."
      }
    }
  ]
}

Respond to Intervention

POST /api/v1/threads/{thread_id}/interventions/{intervention_id}/respond/

Request Body

{
  "response": {
    "approved": true,
    "message": "Yes, provide the standard enterprise pricing information."
  }
}

Response

{
  "id": "int_123",
  "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "approval_required",
  "status": "completed",
  "created_at": "2023-01-01T12:10:00Z",
  "response_at": "2023-01-01T12:12:00Z"
}

WebSockets

For real-time updates on threads, messages, and interventions, you can establish WebSocket connections.

wss://api.polmy.ai/ws/thread/{thread_id}/

Authentication

Connect with your API key in the query parameters:

wss://api.polmy.ai/ws/thread/3fa85f64-5717-4562-b3fc-2c963f66afa6/?token=YOUR_API_KEY

Message Types

message: New message in the thread
intervention: New intervention request
status: Thread status changes

Example Event

{
  "type": "message",
  "data": {
    "id": "msg_126",
    "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2023-01-01T12:15:00Z",
    "role": "assistant",
    "content": "Here's the information about setting up a knowledge store...",
    "status": "delivered"
  }
}

Rate Limits

API requests are subject to rate limiting based on your subscription plan.

Plan	Knowledge Store Queries	Agent Messages	Concurrent Threads
Free	100 / day	50 / day	5
Standard	1,000 / day	500 / day	20
Business	10,000 / day	5,000 / day	100
Enterprise	Custom	Custom	Custom

Rate limit headers are included in API responses to help you track your usage.

API Playground

Try out our APIs interactively in our API Playground.

Knowledge Store API Playground

Test queries against your knowledge stores and see results in real-time.

Try Knowledge Store API

Agent API Playground

Test agent interactions and see how threads and messages work.

Try Agent API