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

# Completions API

> Use our OpenAI-compatible chat completions API to integrate with any platform.

<Warning>
  **Deprecated.** This endpoint is deprecated and will be **sunset on 2026-07-11**. It still works until then. Migrate to the V1 path -- see the [migration guide](/en/migrations/2026-06-outbound-api-v1) for the old -> new path table.
</Warning>

The API integration provides an OpenAI-compatible chat completions endpoint that you can use to interact with your Pathors project.

## Base URL

```
https://api.pathors.com
```

## Chat Completions

```bash theme={null}
POST https://api.pathors.com/project/{projectId}/chat/completions
```

### Path Parameters

<ParamField path="projectId" type="string" required>
  The ID of your project
</ParamField>

### Request Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication using your Project API Key (starts with `sk_`). Format: `Bearer {your-api-key}`
</ParamField>

<ParamField header="X-Session-ID" type="string">
  Session ID for conversation continuity. Strongly recommended to use this
  header for passing session ID instead of the session\_id parameter in the
  request body.
</ParamField>

### Request Body

<ParamField body="messages" type="array">
  Array of messages in the conversation. Each message should have a `role`
  ("system", "user", or "assistant") and `content`.
</ParamField>

<ParamField body="stream" type="boolean">
  Whether to stream the response. Defaults to false.
</ParamField>

<ParamField body="session_id" type="string">
  (deprecated) Session ID for conversation continuity. It is recommended to use
  the X-Session-ID header instead. Only use this parameter in environments that
  do not support custom headers.
</ParamField>

<ParamField body="tools" type="array">
  Array of external tool definitions that will be available for the assistant to use.
  Each tool should have a `type` (currently only "function" is supported) and a `function`
  object with `name`, `description`, and `parameters` (JSON Schema format).
</ParamField>

Example request:

```bash theme={null}
curl -X POST https://api.pathors.com/project/{projectId}/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user", "content": "Hello!"}], "stream": false}'
```

Example request with tools:

```bash theme={null}
curl -X POST https://api.pathors.com/project/{projectId}/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messages": [{"role": "user", "content": "What's the weather in San Francisco?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather information",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city name"
            }
          },
          "required": ["location"]
        }
      }
    }]
  }'
```

### Response Headers

<ParamField header="X-Session-ID" type="string">
  Session ID for the conversation. This header is returned in the response and can be used in subsequent requests.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the completion
</ResponseField>

<ResponseField name="object" type="string">
  Object type ("chat.completion")
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp of when the completion was created
</ResponseField>

<ResponseField name="model" type="string">
  Model used for the completion
</ResponseField>

<ResponseField name="choices" type="array">
  Array of completion choices
</ResponseField>

<ResponseField name="session_id" type="string">
  Session ID for the conversation
</ResponseField>

<ResponseField name="choices[].message.tool_calls" type="array">
  Array of tool calls made by the assistant (when tools are provided and used)
</ResponseField>

<ResponseField name="choices[].finish_reason" type="string">
  Reason for completion termination. Can be "stop" for normal completion or "tool\_calls" when tools are invoked.
</ResponseField>

Example response:

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "pathway-default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": -1,
    "completion_tokens": -1,
    "total_tokens": -1
  },
  "session_id": "session-xyz789"
}
```

Example response with tool calls:

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "pathway-default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": -1,
    "completion_tokens": -1,
    "total_tokens": -1
  },
  "session_id": "session-xyz789"
}
```

### Streaming Response

When `stream` is set to `true`, the response will be a stream of server-sent events (SSE). Each event contains a chunk of the response in the following format:

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion.chunk",
  "created": 1677858242,
  "model": "pathway-default",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hi"
      },
      "finish_reason": null
    }
  ],
  "session_id": "session-xyz789"
}
```

The final chunk will have `finish_reason: "stop"` and will be followed by `data: [DONE]`.

### Error Responses

| Status Code | Description            |
| ----------- | ---------------------- |
| 400         | Invalid request body   |
| 401         | Invalid authentication |
| 500         | Internal server error  |

## Working with Tools

When you provide tools in the request, the assistant can invoke them during the conversation. After receiving a response with `tool_calls`, you should:

1. Execute the requested tools with the provided arguments
2. Send the tool results back in a follow-up request with "tool" role messages
3. The assistant will then use the tool results to formulate its final response

### Tool Message Format

After receiving tool calls, send the results back:

```json theme={null}
{
  "messages": [
    {"role": "user", "content": "What's the weather?"},
    {
      "role": "assistant",
      "content": "",
      "tool_calls": [
        {
          "id": "call_123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"San Francisco\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "72°F, sunny",
      "tool_call_id": "call_123",
      "name": "get_weather"
    }
  ],
  "session_id": "existing_session_id"
}
```

## Setup Guide

1. Go to **Project Settings > API Keys** and create a new API key
2. Copy the key immediately (it is only shown once)
3. Use the API key in the `Authorization: Bearer {your-api-key}` header for your requests
4. (Optional) Create sessions for conversation continuity using the [Session API](/api-reference/session/create-session)
5. (Optional) Define and provide tools for extended functionality