Chat AI API

GET /api/chat/folders

Gets a list of all chat folders belonging to the authenticated actor.

Successful Response (200 OK)

{
    "folders": [
        {
            "id": 1,
            "name": "Personal Trips",
            "conversation_count": 5
        },
        {
            "id": 2,
            "name": "Client Inquiries",
            "conversation_count": 12
        }
    ]
}

POST /api/chat/folders

Creates a new chat folder.

Request Body

{
    "name": "New Projects"
}

Successful Response (201 Created)

Returns the newly created folder object.

{
    "folder": {
        "id": 3,
        "name": "New Projects",
        "conversation_count": 0
    }
}

PUT /api/chat/folders/<folder_id>

Renames an existing folder.

Request Body

{
    "new_name": "Archived Projects"
}

Successful Response (200 OK)

Returns the updated folder object.

DELETE /api/chat/folders/<folder_id>

Deletes a folder. The conversations it contained are not deleted; they simply become unassigned from any folder.

Successful Response (200 OK)

{
    "message": "Folder ID 3 deleted successfully."
}

GET /api/chat/conversations/unfoldered

Gets a list of conversations that are not assigned to any folder.

Successful Response (200 OK)

Returns an array of conversation objects.

GET /api/chat/folders/<folder_id>/conversations

Gets a list of all conversations within a specific folder.

Successful Response (200 OK)

Returns an array of conversation objects.

PUT /api/chat/conversations/<conversation_id>/move

Moves a conversation to a different folder. To remove a conversation from its folder, use null as the value.

Request Body

{
    "folder_id": 2
}

Successful Response (200 OK)

Returns the updated conversation object.

POST /api/chat/conversations

Creates a new conversation. Optionally, it can be assigned to a folder and/or a custom GPT upon creation. If you provide chat_gpt_id, the ID must correspond to an accessible and active GPT for the authenticated actor.

Request Body

{
    "title": "Planning a trip to Japan",
    "folder_id": 1,
    "chat_gpt_id": 7
}

Successful Response (201 Created)

Returns the newly created conversation object.

GET /api/chat/conversations/<conversation_id>/messages

Retrieves the complete message history of a conversation.

Successful Response (200 OK)

{
    "messages": [
        {
            "role": "user",
            "content": "What are the best months to visit Kyoto?",
            "timestamp": "..."
        },
        {
            "role": "assistant",
            "content": "The best months to visit Kyoto are...",
            "timestamp": "..."
        }
    ]
}

POST /api/chat/conversations/<conversation_id>/messages

Sends a message to an existing conversation and gets a response from the AI assistant. This action consumes tokens.

Request Body

{
    "message": "What are the best months to visit Kyoto?"
}

Successful Response (200 OK)

{
    "reply": "The best months to visit Kyoto are spring (March-May) for the cherry blossoms, and autumn (October-November) for the vibrant colors...",
    "tokens_remaining": 98
}

POST /api/chat/conversations/<conversation_id>/upload

Uploads a document (.pdf, .txt, .md) to a conversation so its content can be used as context in subsequent messages.

Request Body

The request must be of type multipart/form-data. The file must be sent under the key document.

curl -X POST "https://capdata.es/api/chat/conversations/42/upload" \
     -H "X-CapData-Token: your_api_key_or_token" \
     -F "document=@/path/to/your/hotel_booking.pdf"

Successful Response (200 OK)

{
    "success": true,
    "message": "File 'hotel_booking.pdf' parsed and added to the context of this conversation. You can now ask questions about it."
}

GET /api/chat/gpts

Gets a list of all GPTs accessible to the actor (including those imported from global ones). The response includes metadata such as knowledge_file_count, is_global_origin, and display_type.

Successful Response (200 OK)

{
  "gpts": [
    {
      "id": 7,
      "name": "Travel Assistant",
      "description": "Specialized in routes and airlines",
      "is_active": true,
      "knowledge_file_count": 3,
      "is_global_origin": false,
      "display_type": "Client"
    }
  ]
}

GET /api/chat/gpts/available-global

Lists the available global GPTs that can be imported by the client.

Successful Response (200 OK)

{
  "available_global_gpts": [
    {
      "id": 3,
      "name": "Hotel Template",
      "description": "Base for hotel customer service",
      "is_global": true,
      "can_import": true,
      "knowledge_file_count": 5
    }
  ]
}

POST /api/chat/gpts/import/<global_gpt_id>

Imports a global GPT for the authenticated client.

Successful Response (201 Created)

{
  "message": "GPT 'Hotel Template' imported successfully.",
  "imported_gpt": {
    "id": 12,
    "name": "Hotel Template",
    "is_active": true
  }
}

POST /api/chat/gpts

Creates a new custom GPT with its knowledge files.

Request Body

The request must be multipart/form-data with the following fields:

• name (string, required)
• system_prompt (string, required)
• description (string, optional)
• is_active (boolean, optional; defaults to true)
• knowledge_files[] (one or more .pdf/.txt/.md files)

curl -X POST "https://capdata.es/api/chat/gpts" \
  -H "X-CapData-Token: your_api_key_or_token" \
  -F "name=Sales Assistant" \
  -F "system_prompt=Respond like an expert sales advisor" \
  -F "description=Trained with product PDFs" \
  -F "is_active=true" \
  -F "knowledge_files=@/path/to/catalog.pdf" \
  -F "knowledge_files=@/path/to/procedures.txt"

Successful Response (201 Created)

{
  "gpt": {
    "id": 21,
    "name": "Sales Assistant",
    "description": "Trained with product PDFs",
    "is_active": true,
    "knowledge_file_count": 2
  }
}