Create chat completion

POST

/chat/completions

const url = 'https://api.siteassist.io/v2/chat/completions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"messages":[{"role":"user","content":"Hi"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.siteassist.io/v2/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "messages": [ { "role": "user", "content": "Hi" } ] }'

Create a chat completion using the configured assistant. Supports streaming (Server-Sent Events) and non-streaming JSON responses. Streaming returns incremental tokens, while non-streaming returns the full completion along with token usage.

Authorizations

bearerAuth

Request Body

application/json

Messages and options for generating a chat completion. Set ‘stream’ to true to receive a text/event-stream response.

object

assistantId

Assistant to use to generate the response. If not provided then will use the default assistant.

string format: uuid

messages

required

A list of messages comprising the conversation so far.

Array

One of:

Developer-provided instructions that the model should follow, regardless of messages sent by the user. With o1 models and newer, use developer messages for this purpose instead.

object

role

required

The role of the messages author, in this case system.

string

Allowed values: system

content

required

The contents of the system message.

string

Messages sent by an end user, containing prompts or additional context information.

object

role

required

The role of the messages author, in this case user.

string

Allowed values: user

content

required

The contents of the user message.

string

Messages sent by the model in response to user messages.

object

role

required

The role of the messages author, in this case assistant.

string

Allowed values: assistant

content

required

The contents of the assistant message.

string

stream

If set to true, the model response data will be streamed to the client as it is generated using server-sent events.

boolean

Example

{
  "messages": [
    {
      "role": "user",
      "content": "Hi"
    }
  ]
}

Responses

200

Successfully generated a chat completion

Server-sent events stream containing incremental updates of the assistant’s response in Vercel AI SDK UI stream format.

string

Example

data: {"type":"start"}

data: {"type":"start-step"}

data: {"type":"text-start","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","providerMetadata":{"openai":{"itemId":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18"}}}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"Hello! "}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"How "}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"can "}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"I "}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"assist "}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"you "}

data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"today?"}

data: {"type":"text-end","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18"}

data: {"type":"finish-step"}

data: {"type":"finish"}

data: [DONE]

Complete response when streaming is disabled. Contains full content, finish reason, and token usage.

object

steps

required

Array of steps that make up the complete AI response

Array<object>

A single step in the AI response generation process

object

content

required

Array of content blocks in the response. Each block contains the generated content with its type and data.

Array<object>

object

key

additional properties

nullable

finishReason

required

The reason why the model stopped generating content. Common values include ‘stop’, ‘length’, ‘content_filter’, etc.

string

usage

required

Token usage statistics for this response

object

inputTokens

required

Number of tokens in the input prompt

number

outputTokens

required

Number of tokens in the generated response

number

totalTokens

required

Total number of tokens used (input + output)

number

reasoningTokens

required

Number of tokens used for reasoning (for models that support it)

number

cachedInputTokens

required

Number of input tokens that were cached and reused

number

Example

{
  "steps": [
    {
      "content": [
        {
          "type": "text",
          "text": "Hello! How can I assist you today?"
        }
      ],
      "finishReason": "stop",
      "usage": {
        "inputTokens": 2409,
        "outputTokens": 11,
        "totalTokens": 2420,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      }
    }
  ]
}

202

Successfully generated a non-streaming chat completion (full JSON response)

application/json

Complete response when streaming is disabled. Returned with 202 to indicate the completion was generated without streaming.

object

steps

required

Array of steps that make up the complete AI response

Array<object>

A single step in the AI response generation process

object

content

required

Array of content blocks in the response. Each block contains the generated content with its type and data.

Array<object>

object

key

additional properties

nullable

finishReason

required

The reason why the model stopped generating content. Common values include ‘stop’, ‘length’, ‘content_filter’, etc.

string

usage

required

Token usage statistics for this response

object

inputTokens

required

Number of tokens in the input prompt

number

outputTokens

required

Number of tokens in the generated response

number

totalTokens

required

Total number of tokens used (input + output)

number

reasoningTokens

required

Number of tokens used for reasoning (for models that support it)

number

cachedInputTokens

required

Number of input tokens that were cached and reused

number

Example

{
  "steps": [
    {
      "content": [
        {
          "type": "text",
          "text": "Hello! How can I assist you today?"
        }
      ],
      "finishReason": "stop",
      "usage": {
        "inputTokens": 2409,
        "outputTokens": 11,
        "totalTokens": 2420,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      }
    }
  ]
}

400

Bad Request - The request body or parameters are invalid

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Invalid request body. Content is required.",
    "code": "INVALID_REQUEST_BODY",
    "details": {
      "field": "content"
    }
  }
}

401

Unauthorized - Authentication token is missing or invalid

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Authentication required",
    "code": "UNAUTHORIZED"
  }
}

402

Payment Required - A higher pricing plan is required to access the resource

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "A higher pricing plan is required to access this feature",
    "code": "PAYMENT_REQUIRED",
    "details": {
      "currentPlan": "free",
      "requiredPlan": "pro",
      "feature": "advanced_ai_models"
    }
  }
}

403

Forbidden - Access denied to the requested resource

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Access denied to this conversation",
    "code": "FORBIDDEN"
  }
}

404

Not Found - The requested resource was not found

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Conversation not found!",
    "code": "CONVERSATION_NOT_FOUND",
    "details": {
      "conversationId": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

409

Conflict - The request could not be completed due to a conflict

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Resource already exists",
    "code": "CONFLICT",
    "details": {
      "resource": "conversation",
      "conflictingField": "id"
    }
  }
}

422

Unprocessable Entity - The request was well-formed but contains semantic errors

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "field": "content",
      "reason": "Content exceeds maximum length of 10000 characters"
    }
  }
}

429

Too Many Requests - Rate limit exceeded or quota reached

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retryAfter": 60
    }
  }
}

500

Internal Server Error - An unexpected error occurred

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "An internal server error occurred",
    "code": "INTERNAL_SERVER_ERROR"
  }
}

502

Bad Gateway - The server received an invalid response from an upstream server

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "BAD_GATEWAY",
    "details": {
      "service": "ai_model_service"
    }
  }
}

503

Service Unavailable - The server is temporarily unable to handle the request

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "SERVICE_UNAVAILABLE",
    "details": {
      "retryAfter": 30
    }
  }
}