POST
/
api
/
project
/
{projectId}
/
integration
/
api
/
chat
/
completions
Completions API
curl --request POST \
  --url https://app.pathors.com/api/project/{projectId}/integration/api/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {}
  ],
  "stream": true,
  "session_id": "<string>",
  "tools": [
    {}
  ]
}'
{
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {}
  ],
  "session_id": "<string>",
  "choices[].message.tool_calls": [
    {}
  ],
  "choices[].finish_reason": "<string>"
}
The API integration provides an OpenAI-compatible chat completions endpoint that you can use to interact with your Pathors project.

​
Chat Completions

POST /api/project/{projectId}/integration/api/chat/completions

​
Path Parameters

​
projectId
string
required
The ID of your project

​
Request Headers

​
Authorization
string
required
Bearer token authentication using your API key
​
X-Session-ID
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.

​
Request Body

​
messages
array
Array of messages in the conversation. Each message should have a role (“system”, “user”, or “assistant”) and content.
​
stream
boolean
Whether to stream the response. Defaults to false.
​
session_id
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.
​
tools
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).
Example request: 
curl -X POST https://app.pathors.com/api/project/{projectId}/integration/api/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"messages": [{"role": "user", "content": "Hello!"}], "stream": false}'
Example request with tools: 
curl -X POST https://app.pathors.com/api/project/{projectId}/integration/api/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

​
X-Session-ID
string
Session ID for the conversation. This header is returned in the response and can be used in subsequent requests.

​
Response

​
id
string
Unique identifier for the completion
​
object
string
Object type (“chat.completion”)
​
created
number
Unix timestamp of when the completion was created
​
model
string
Model used for the completion
​
choices
array
Array of completion choices
​
session_id
string
Session ID for the conversation
​
choices[].message.tool_calls
array
Array of tool calls made by the assistant (when tools are provided and used)
​
choices[].finish_reason
string
Reason for completion termination. Can be “stop” for normal completion or “tool_calls” when tools are invoked.
Example response: 
{
  "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: 
{
  "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: 
{
  "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 CodeDescription
400Invalid request body
401Invalid authentication
500Internal 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: 
{
  "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. Enable the API integration in your Pathors project settings
  2. Generate an API key in your project’s integration settings
  3. Use the API key in the Authorization header for your requests
  4. (Optional) Create sessions for conversation continuity using the Session API
  5. (Optional) Define and provide tools for extended functionality