POST /chat - SundayPyjamas AI Suite

Overview

The POST /chat endpoint is the primary way to interact with SundayPyjamas AI models. It accepts a conversation history and returns an AI-generated response as a streaming text.

All responses are streamed in real-time for better user experience in conversational applications.

Authentication

Authorization

string

required

Bearer token with your API key. Format: Bearer spj_ai_your_api_key_here

Request Body

messages

Array<Message>

required

Array of conversation messages. Must contain at least one message with valid content.

Show Message Object

role

string

required

The role of the message sender. Must be one of:

user - Messages from the user/human
assistant - Previous AI responses in the conversation
system - System instructions to guide AI behavior

content

string

required

The message content. Cannot be empty or null.

model

string

default:"llama-3.3-70b-versatile"

AI model to use for generating the response. Currently available models:

llama-3.3-70b-versatile - High-quality general-purpose model (default)

Response

Headers

The response includes the following headers for streaming:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Body

response

string

Streaming text response from the AI model. The complete response is built by concatenating all streamed chunks.

Examples

Basic Request

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Write a professional email greeting."
      }
    ]
  }'

Hello! Here's a professional email greeting for you:

Dear [Recipient's Name],

I hope this email finds you well. I wanted to reach out to discuss [purpose of email].

Best regards,
[Your Name]

With System Message

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a technical writer who creates clear, concise documentation."
      },
      {
        "role": "user",
        "content": "Explain what an API is in simple terms."
      }
    ]
  }'

An API (Application Programming Interface) is like a waiter in a restaurant:

- You (the customer) make a request for food
- The waiter takes your order to the kitchen
- The kitchen prepares your meal  
- The waiter brings back your food

Similarly, an API:
- Receives requests from applications
- Processes those requests
- Returns the requested data or performs actions
- Enables different software systems to communicate

APIs make it possible for apps on your phone to get weather data, social media feeds, or payment processing without having to build those services themselves.

Multi-turn Conversation

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is machine learning?"
      },
      {
        "role": "assistant",
        "content": "Machine learning is a subset of artificial intelligence (AI) that enables computers to learn and improve from experience without being explicitly programmed for every task."
      },
      {
        "role": "user",
        "content": "Can you give me a simple example?"
      }
    ]
  }'

Sure! Here's a simple example:

**Email Spam Detection**

1. **Training**: You show the computer thousands of emails labeled as "spam" or "not spam"
2. **Learning**: The computer finds patterns - spam emails often have words like "FREE!", "URGENT!", multiple exclamation marks, or suspicious links
3. **Prediction**: When a new email arrives, the computer uses these learned patterns to predict if it's spam or not

The computer "learned" to recognize spam without being programmed with explicit rules like "if email contains 'FREE!' then it's spam." Instead, it discovered these patterns by analyzing examples.

Other everyday examples:
- Netflix recommending movies based on what you've watched
- Your phone's autocorrect learning your typing patterns
- Banks detecting fraudulent transactions

Specifying Model

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Generate a Python function to calculate fibonacci numbers."
      }
    ],
    "model": "llama-3.3-70b-versatile"
  }'

Content Generation

curl -X POST https://suite.sundaypyjamas.com/api/v1/chat \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a marketing copywriter. Write compelling copy that drives action and focuses on benefits."
      },
      {
        "role": "user",
        "content": "Write marketing copy for a productivity app targeting remote workers. Include a headline, 3 key benefits, and a call-to-action."
      }
    ]
  }'

Error Responses

400 Bad Request

{
  "error": "Messages array is required"
}

{
  "error": "Last message must have valid content"
}

{
  "error": "Invalid request body"
}

401 Unauthorized

{
  "error": "Invalid API key"
}

403 Forbidden

{
  "error": "Token limit exceeded"
}

{
  "error": "Insufficient permissions"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded"
}

500 Internal Server Error

{
  "error": "Failed to generate response"
}

Streaming Implementation

JavaScript/TypeScript

async function streamChatResponse(messages: ChatMessage[]) {
  const response = await fetch('/api/v1/chat', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ messages })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  let fullResponse = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    fullResponse += chunk;
    
    // Process each chunk in real-time
    onChunk(chunk);
  }

  return fullResponse;
}

Python

import requests

def stream_chat_response(messages):
    response = requests.post(
        'https://suite.sundaypyjamas.com/api/v1/chat',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
        },
        json={'messages': messages},
        stream=True
    )
    
    response.raise_for_status()
    
    full_response = ''
    for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
        if chunk:
            full_response += chunk
            # Process each chunk in real-time
            print(chunk, end='', flush=True)
    
    return full_response

Go

package main

import (
    "bufio"
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func streamChatResponse(messages []Message) (string, error) {
    requestBody := ChatRequest{Messages: messages}
    jsonData, _ := json.Marshal(requestBody)
    
    req, _ := http.NewRequest("POST", "https://suite.sundaypyjamas.com/api/v1/chat", 
        bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()
    
    if resp.StatusCode != http.StatusOK {
        // Handle error response
        var errorResp ErrorResponse
        json.NewDecoder(resp.Body).Decode(&errorResp)
        return "", fmt.Errorf("API error: %s", errorResp.Error)
    }
    
    scanner := bufio.NewScanner(resp.Body)
    var fullResponse strings.Builder
    
    for scanner.Scan() {
        chunk := scanner.Text()
        fullResponse.WriteString(chunk)
        // Process each chunk in real-time
        fmt.Print(chunk)
    }
    
    return fullResponse.String(), nil
}

Request Validation

Message Array Requirements

Valid Message Structure

{
  "messages": [
    {
      "role": "user",
      "content": "Your message here"
    }
  ]
}

✅ Valid: Contains required fields with proper types

Invalid Examples

{
  "messages": []
}

❌ Invalid: Empty messages array

{
  "messages": [
    {
      "role": "user"
    }
  ]
}

❌ Invalid: Missing content field

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

❌ Invalid: Empty content string

{
  "messages": [
    {
      "role": "invalid_role",
      "content": "Hello"
    }
  ]
}

❌ Invalid: Invalid role value

Content Length Limits

Very long requests may hit token limits. Consider breaking large content into smaller chunks or summarizing previous context.

Practical limits:

Single message: ~10,000 characters recommended
Total conversation: ~20,000 characters for optimal performance
Token estimation: ~4 characters per token

Rate Limiting Details

Token Usage

Input + output tokens count toward workspace limits

Request Rate

No hard limits, but monitored for abuse

Concurrent Requests

Multiple simultaneous requests supported

Fair Usage

Excessive usage may be throttled

Optimization Tips

To optimize your usage:

Use clear, concise prompts
Trim conversation history to relevant context
Batch similar requests when possible
Monitor token usage through workspace analytics

Testing with Different Tools

Postman

POST https://suite.sundaypyjamas.com/api/v1/chat
Headers:
  Authorization: Bearer spj_ai_your_api_key_here
  Content-Type: application/json
  
Body (raw JSON):
{
  "messages": [
    {
      "role": "user",
      "content": "Test message"
    }
  ]
}

HTTPie

http POST https://suite.sundaypyjamas.com/api/v1/chat \
  Authorization:"Bearer spj_ai_your_api_key_here" \
  messages:='[{"role": "user", "content": "Test message"}]'

Insomnia

{
  "method": "POST",
  "url": "https://suite.sundaypyjamas.com/api/v1/chat",
  "headers": {
    "Authorization": "Bearer spj_ai_your_api_key_here",
    "Content-Type": "application/json"
  },
  "body": {
    "messages": [
      {
        "role": "user",
        "content": "Test message"
      }
    ]
  }
}

Performance Considerations

Response Times

Typical response times vary based on:

Request complexity: Simple queries respond faster
Response length: Longer responses take more time
Server load: Peak times may have slightly longer latencies

Expected ranges:

Simple queries: 1-3 seconds
Complex content generation: 3-10 seconds
Very long responses: 10-30 seconds

Best Practices

Optimize for Speed

Use specific, focused prompts
Limit conversation history to relevant context
Request shorter responses when appropriate
Use streaming to show progress to users

Handle Timeouts

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout

try {
  const response = await fetch('/api/v1/chat', {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({ messages }),
    signal: controller.signal
  });
  
  clearTimeout(timeoutId);
  // Process response...
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request timed out');
  }
}

Connection Management

Reuse HTTP connections when possible
Implement proper connection pooling
Handle network interruptions gracefully
Use appropriate timeouts for your use case

Next Steps

Code Examples

See complete implementation examples in multiple languages

Error Handling

Learn comprehensive error handling patterns

Rate Limits

Understand usage optimization and monitoring

Authentication

Manage API keys and security best practices

Chat API

​Overview

​Authentication

​Request Body

​Response

​Headers

​Body

​Examples

​Basic Request

​With System Message

​Multi-turn Conversation

​Specifying Model

​Content Generation

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​500 Internal Server Error

​Streaming Implementation

​JavaScript/TypeScript

​Python

​Go

​Request Validation

​Message Array Requirements

​Content Length Limits

​Rate Limiting Details

Token Usage

Request Rate

Concurrent Requests

Fair Usage

​Optimization Tips

​Testing with Different Tools

​Postman

​HTTPie

​Insomnia

​Performance Considerations

​Response Times

​Best Practices

​Next Steps

Code Examples

Error Handling

Rate Limits

Authentication

Overview

Authentication

Request Body

Response

Headers

Body

Examples

Basic Request

With System Message

Multi-turn Conversation

Specifying Model

Content Generation

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Streaming Implementation

JavaScript/TypeScript

Python

Go

Request Validation

Message Array Requirements

Content Length Limits

Rate Limiting Details

Optimization Tips

Testing with Different Tools

Postman

HTTPie

Insomnia

Performance Considerations

Response Times

Best Practices

Next Steps