> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawa-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Requests

> With Pawa AI APIs you can use our models that has been fine-tuned to follow instructions and respond to natural language prompts through chat using prompt.

Chat requests includes anything from summarizing articles, generating creative writing, answering questions, providing customer support, to assisting with coding tasks in prompts.

A **prompt** is the input you provide to the model. It can take various forms, such as asking a question, giving an instruction, or providing a few examples of a task you want the model to perform. Based on this input, the model generates a text output as a response.

The **[Chat request API](/api-reference/endpoint/chat/request?playground=open)** accepts a list of chat messages as input and generates a response. For request messages, send `"content"` as a list of typed content blocks, even for plain text. A text-only message should use this shape: `"content": [{ "type": "text", "text": "Your message here" }]`. The response is returned as a new chat message with the role `"assistant"`, and response `"content"` may be returned as a string.

***

### A Basic Chat Request Example

```bash theme={null}
curl --request POST \
 --url https://api.pawa-ai.com/v1/chat/request \
 --header "Authorization: Bearer $PAWA_AI_API_KEY" \  
 --header 'Content-Type: application/json' \
 --data '{
        "model": "pawa-v1-ember-20240924",
        "messages": [
          {
            "role": "system",
            "content": [
              {
                "type": "text",
                "text": "You are a TanzaBot, a helpful AI assistant for answering questions about Tanzania"
              }
            ]
          },
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "Hello what is top three attractions in Tanzania, that i should visit?"
              }
            ]
          }
        ]}'
```

### Sample Response Example

```bash theme={null}
{
  "success": true,
  "message": "Chat request processed successfully",
  "data": {
    "request": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "1. Serengeti National Park: Known for its vast plains, the Great Migration, and diverse wildlife, Serengeti is a must-visit for nature lovers.\n\n2. Ngorongoro Crater: A UNESCO World Heritage Site, this crater is home to the Ngorongoro Conservation Area, offering a unique blend of wildlife, culture, and geology.\n\n3. Kilimanjaro National Park: The highest mountain in Africa, Kilimanjaro offers a challenging trekking experience and stunning views from the summit."
        },
        "matched_stop": 128001
      }
    ],
    "created": "2025-09-09",
    "model": "pawa-v1-ember-20240924",
    "object": "chat.request"
  }
}
```

> Finish reason can be of `stop` means the generation endeded, or `tool` means tool was called instead, or `cancelled` if the generation was aborted. You can use this to see the reason behind the event occured during the generation, forexample when request has a `tool calling` you can use it to detect and process that request.

### Chat Messages

Chat messages (messages) are a collection of prompts or messages, with each message having a specific role assigned to it, such as **system**, **user**, **assistant**, or **tool**.

A **system message** is an optional message that sets the behavior and context for an AI assistant in a conversation, such as modifying its personality or providing specific instructions. A system message can include task instructions, personality traits, contextual information, creativity constraints, and other relevant guidelines to help the AI better understand and respond to the user's input.\
See the API reference for explanations on how to set up a custom system prompt.

A **user message** is a message sent from the perspective of the human in a conversation with an AI assistant. It typically provides a request, question, or comment that the AI assistant should respond to. User prompts allow the human to initiate and guide the conversation, and they can be used to request information, ask for help, provide feedback, or engage in other types of interaction with the AI.

An **assistant message** is a message sent by the AI assistant back to the user. It is usually meant to reply to a previous user message by following its instructions, but you can also find it at the beginning of a conversation, for example to greet the user.

A **tool message** only appears in the context of function calling. It is used at the final response formulation step when the model has to format the tool call's output for the user.\
To learn more about function calling, see the guide.

***

### Message Role Orders Required

Our message role ordering follows the alternate structure — you **cannot send two consecutive messages with the same role**.\
If you need to add additional context to a role, include it inside the `content` list instead of repeating the role.

You can mix **system**, **user**, or **assistant** roles in alternate order for your conversation context.

***

#### Example Valid Messages

```json theme={null}
[
  {"role": "system", "content": [{"type": "text", "text": "..."}]},
  {"role": "user", "content": [{"type": "text", "text": "..."}]},
  {"role": "assistant", "content": [{"type": "text", "text": "..."}]},
  {"role": "user", "content": [{"type": "text", "text": "..."}]}
]
```

#### Invalid: Plain String Content

```json theme={null}
[
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Hello"}
]
```

#### Invalid: Consecutive Messages With the Same Role

```json theme={null}
[
  {"role": "system", "content": [{"type": "text", "text": "..."}]},
  {"role": "user", "content": [{"type": "text", "text": "..."}]},
  {"role": "user", "content": [{"type": "text", "text": "..."}]},
  {"role": "assistant", "content": [{"type": "text", "text": "..."}]}
]
```

#### Correct Way to Add Context to the Same Role

```json theme={null}
[
  {"role": "system", "content": [
    {
      "type": "text", 
      "text": "You are a helpful assistant."
    },
    {
      "type": "text", 
      "text": "Answer briefly."
    },
    {
      "type": "text", 
      "text": "Use Swahili when the user writes in Swahili."
    }
  ]},
  {"role": "user", "content": [{"type": "text", "text": "..."}]},
  {"role": "assistant", "content": [{"type": "text", "text": "..."}]}
]

```

### Stop Generation

Unlike to other providers, our **[Chat request API](/api-reference/endpoint/chat/request?playground=open)** has built-in aborting generation mechanism in nature that you can send signal in your front-end to abort the generation anytime. Please check examples front-end code in typescript using `AbortSignal`.