Quick Start Using APIs

This guide will help you get started with the Completions API from ProRata. You’ll learn how to authenticate, send your first message, and handle streaming responses using Server-Sent Events (SSE).

Prerequisites

To use the API, you'll need:

An API key (Bearer token)
Your User ID (X-User-ID)
A tool like curl, Postman, or any HTTP client

For Python developers:

Python 3.7+
requests library
Optionally, for streaming support, the sseclient-py package (only required for streaming)

Install dependencies:

pip install requests
pip install sseclient-py  # Optional, for streaming only

Authentication

All requests must include the following headers:

Authorization: Bearer <your_access_token>
X-User-ID: <your_user_id>

headers = {
    "Authorization": "Bearer <your_access_token>",
    "X-User-ID": "<your_user_id>",
    "Content-Type": "application/json"
}

Replace <your_access_token> and <your_user_id> with your actual values.

Send Your First Request

Here’s a simple example for sending a chat prompt to the API:

# Set your API key (shared out-of-band with partners)
export API_KEY=pk_9bedc9f...

curl -X POST https://api.staging.prorata.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-ID: test-user" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Why is the sky blue?" }
    ]
  }'

import requests

API_KEY = "pk_9bedc9f..."       # Replace with your API key
USER_ID = "test-user"           # Replace with your user ID

url = "https://api.staging.prorata.ai/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "X-User-ID": USER_ID,
    "Content-Type": "application/json"
}
payload = {
    "messages": [
        {"role": "user", "content": "Why is the sky blue?"}
    ]
}

# stream=False by default; omit or set explicitly if desired
response = requests.post(url, headers=headers, json=payload)

if response.ok:
    print("Response JSON:")
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")

Handling Streaming Responses (SSE)

When using streaming mode, the API returns data incrementally via Server-Sent Events (SSE). Example output:

Note: in Python, install and use the sseclient-py package

event: metadata
data: {"threadId":"9e378733-5405-4ac3-b29a-f6cdb6ec042a","turnId":"1","title":"Why is the sky blue?"}

event: generating
data: {"content": "The sky appears blue because of a phenome"}

event: generating
data: {"content": "non called **Rayleigh scattering**, which o"}

...

event: generating
data: {"content": "range [7]."}

event: complete
data: {}

import requests
import sseclient

API_KEY = "pk_9bedc9f..."       # Replace with your API key
USER_ID = "test-user"           # Replace with your user ID

url = "https://api.staging.prorata.ai/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "X-User-ID": USER_ID,
    "Content-Type": "application/json"
}
payload = {
    "messages": [
        {"role": "user", "content": "Why is the sky blue?"}
    ],
    "stream": True  # Enable streaming mode
}

response = requests.post(url, headers=headers, json=payload, stream=True)
client = sseclient.SSEClient(response)

for event in client.events():
    print(f"Event: {event.event}")
    print(f"Data: {event.data}")

📌 What’s Important Here?

threadId: Identifies the ongoing conversation
turnId: Identifies a specific response

These values are required to construct follow-up messages.

Follow-Up Request Example

To reference a previous response, include a message with "role": "assistant" and the relevant metadata (threadId and turnId):

curl -X POST https://api.staging.prorata.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-ID: test-user" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Why is the sky black at night?" },
      { 
        "role": "assistant", 
        "metadata": {
          "thread_id": "bfb5862e-1772-4f82-9297-7e533e0cca73",
          "turn_id": "1"
        }
      }
    ]
  }'

# Assumes imports and variables (API_KEY, USER_ID, url, headers) defined as above

payload = {
    "messages": [
        {"role": "user", "content": "Why is the sky black at night?"},
        {
            "role": "assistant",
            "metadata": {
                "thread_id": "bfb5862e-1772-4f82-9297-7e533e0cca73",
                "turn_id": "1"
            }
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)

if response.ok:
    print("Follow-up response JSON:")
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")