Guide · Developers

API Guide

A step-by-step guide to interacting with the Toqan API, from setup to file handling and multi-turn conversations.

Sean Kenny · Senior Product Manager May 12, 2026 6 min read

This guide walks you through the core Toqan API flows:

  • Setting up an Agent and generating an API key
  • Creating a conversation and retrieving a response
  • Uploading a file and asking questions about it
  • Continuing a conversation across multiple turns
  • Downloading a result file

Setup

Go to work.toqan.ai/spaces/create to create a new Agent. Type general in the text area to create a universal Agent, then open the API tab to generate an API key.

Your API key starts with sk_. Store it securely, you’ll need it for every request.

Use the Toqan web interface to configure your system prompt, instructions, and tools before going to the API.

Create a conversation

Start a conversation by sending a message to the Agent:

curl --request POST \
     --url https://api.coco.prod.toqan.ai/api/create_conversation \
     --header 'X-Api-Key: <YOUR_API_KEY_HERE>' \
     --header 'content-type: application/json' \
     --data '{
       "user_message": "hi"
     }'

The response returns a conversation_id and request_id. Use both to retrieve the answer:

curl --request GET \
     --url https://api.coco.prod.toqan.ai/api/get_answer \
     --header 'X-Api-Key: <YOUR_API_KEY_HERE>' \
     --header 'content-type: application/json' \
     --data '{
       "conversation_id": "<YOUR_CONVERSATION_ID_HERE>",
       "request_id": "<YOUR_REQUEST_ID_HERE>"
     }'

The response includes a status field:

  • in_progress, still processing
  • finished, completed, answer is included
  • error, request failed

Get conversation history

Retrieve the full conversation history using the conversation_id:

curl --request POST \
     --url https://api.coco.prod.toqan.ai/api/find_conversation \
     --header 'X-Api-Key: <YOUR_API_KEY_HERE>' \
     --header 'content-type: application/json' \
     --data '{
       "conversation_id": "<YOUR_CONVERSATION_ID_HERE>"
     }'

The response is a JSON array of all messages. The last entry is the result of your most recent query. Useful for long-running operations or tracking progress across a complex conversation.

Upload a file

To attach a file to a conversation, upload it first:

curl --request PUT \
     --url https://api.coco.prod.toqan.ai/api/upload_file \
     --header 'X-Api-Key: <YOUR_API_KEY_HERE>' \
     -F 'file=@/path/to/your/file.txt'

Copy the file_id from the response, you’ll need it in the next step.

Continue a conversation

Continue an existing conversation and attach the uploaded file:

curl --request POST \
     --url https://api.coco.prod.toqan.ai/api/continue_conversation \
     --header 'X-Api-Key: <YOUR_API_KEY_HERE>' \
     --header 'content-type: application/json' \
     --data '{
       "conversation_id": "<YOUR_CONVERSATION_ID_HERE>",
       "private_user_files": [
         {
           "id": "<YOUR_FILE_ID_HERE>"
         }
       ],
       "user_message": "What is in the file?"
     }'

Then retrieve the answer using get_answer with the returned request_id, same as in the create conversation step.

Download a result file

If the Agent produces an output file, download it with:

curl --request GET \
     --url https://api.coco.prod.toqan.ai/api/download_file \
     --header 'X-Api-Key: <YOUR_API_KEY_HERE>' \
     --header 'content-type: application/json' \
     --data '{
       "conversation_id": "<YOUR_CONVERSATION_ID_HERE>",
       "file_name": "your_file.txt"
     }' \
     --output your_file.txt