Chat API & Models

Send a message

curl -X POST "https://api.tarqaai.com/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Explain quantum mechanics." }
    ],
    "stream": false
  }'

The response is a standard chat completion:

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1751760000,
  "model": "gemini-2.5-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Quantum mechanics is a branch of physics..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 28, "completion_tokens": 142, "total_tokens": 170 }
}

Models

There are 60+ models. Always read exact IDs from GET /v1/models or the Models page in your dashboard, because the list changes. Popular ones:

Streaming

Set "stream": true to get the reply word by word as Server-Sent Events. Each event carries a small piece of text, and the stream ends with [DONE].

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Quantum"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" mechanics"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

const stream = await client.chat.completions.create({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Explain quantum mechanics.' }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

Tool calling

On its own, a model can't reach your database, your APIs or the internet. Tool calling lets it ask your app to run something ("look up order 42") and then use the result in its answer.

With custom functions, Tarqa only passes the request and the result along. It never runs your tool or sees anything beyond the arguments and the result you send back.

Try it in the Playground (no code)

1. 1
   Open Functions

   In Build → Playground, click the Functions button under the message box. What you define here only lives in the current Playground session.
2. 2
   Define a tool

   Use Form mode to fill in a name, a description (the model reads this to decide when to use it) and typed parameters. Or switch to JSON and paste a tools array in the same format as the API example below.
3. 3
   Ask something that needs it

   For example: "How many orders did user 42 place last month?" for a query_db tool. It works the same with any model.
4. 4
   Run it yourself and paste the result

   A "The model wants to use a tool" card appears with the arguments. Run that lookup in your own app, paste the result, and click Submit results. The model then finishes its answer.

Call it from the API

It's a three-step round trip.

1. 1
   Send your tools with the message

   Request

   Copy

   {
     "model": "claude-sonnet-4-5",
     "messages": [
       { "role": "user", "content": "How many orders did user 42 place last month?" }
     ],
     "tools": [
       {
         "type": "function",
         "function": {
           "name": "query_db",
           "description": "Run a read-only SQL query against the caller's own database",
           "parameters": {
             "type": "object",
             "properties": { "sql": { "type": "string" } },
             "required": ["sql"]
           }
         }
       }
     ]
   }

2. 2
   The model asks for a tool call

   Response — finish_reason: tool_calls

   Copy

   {
     "id": "chatcmpl-abc123xyz",
     "object": "chat.completion",
     "created": 1751760000,
     "model": "claude-sonnet-4-5",
     "choices": [
       {
         "index": 0,
         "message": {
           "role": "assistant",
           "content": null,
           "tool_calls": [
             {
               "id": "call_1",
               "type": "function",
               "function": { "name": "query_db", "arguments": "{\"sql\":\"SELECT COUNT(*) FROM orders WHERE user_id=42 ...\"}" }
             }
           ]
         },
         "finish_reason": "tool_calls"
       }
     ],
     "usage": { "prompt_tokens": 42, "completion_tokens": 18, "total_tokens": 60 }
   }

3. 3
   Run it, then send back the result

   Include the assistant's tool_calls message and a role: "tool" message with what your tool returned. The model then replies normally with finish_reason: "stop".

   Follow-up request

   Copy

   {
     "model": "claude-sonnet-4-5",
     "messages": [
       { "role": "user", "content": "How many orders did user 42 place last month?" },
       {
         "role": "assistant",
         "content": null,
         "tool_calls": [
           { "id": "call_1", "type": "function", "function": { "name": "query_db", "arguments": "{\"sql\":\"...\"}" } }
         ]
       },
       { "role": "tool", "tool_call_id": "call_1", "content": "{\"count\": 7}" }
     ]
   }

When streaming, tool-call arguments arrive as one complete event (not piece by piece), with finish_reason: "tool_calls" on the delta.tool_calls chunk.

The upcoming Tarqa JS and Python SDKs (not published yet) add a runTools / run_tools helper that handles this whole round trip for you. See SDKs & Libraries.

FAQ