#SDK Quickstart

This document provides quick integration examples for JavaScript/TypeScript, Python, and cURL to help you start using the Creatoria Agent API in minutes.

#Basic Setup

All requests require the following configuration:

Base URL: https://your-domain.com/v1
Authentication: X-API-Key header
Project: X-Project-Id header (optional)

#JavaScript / TypeScript

#Basic Request

javascriptconst BASE_URL = 'https://your-domain.com/v1';
const API_KEY = 'your-api-key';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json',
};

// List Agents
const response = await fetch(`${BASE_URL}/agents`, { headers });
const { data, meta } = await response.json();
console.log(`Found ${meta.total} agents`);

#Non-Streaming Chat

javascriptconst chatResponse = await fetch(`${BASE_URL}/agents/${agentId}/chat`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello' }],
    stream: false,
  }),
});

const result = await chatResponse.json();
console.log(result.data.content);

#Streaming Chat (SSE)

javascriptconst response = await fetch(`${BASE_URL}/agents/${agentId}/chat`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    message: 'Analyze current market trends',
    sessionId: 'optional-session-id',
    stream: true,
  }),
});

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

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop() || '';

  for (const line of lines) {
    if (!line.startsWith('data: ')) continue;
    const data = line.slice(6);
    if (data === '[DONE]') break;

    try {
      const event = JSON.parse(data);
      if (event.delta) process.stdout.write(event.delta);
      if (event.thinking) console.log('[Thinking]', event.thinking);
      if (event.toolCall) console.log('[Tool Call]', event.toolCall.name);
      if (event.toolResult) console.log('[Tool Result]', event.toolResult.name);
    } catch {}
  }
}

#Knowledge Base Operations

javascript// Create knowledge base
const kb = await fetch(`${BASE_URL}/knowledge-bases`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Product Docs',
    description: 'Product documentation and FAQs',
  }),
}).then(r => r.json());

// Upload document
const formData = new FormData();
formData.append('file', fileBlob, 'document.pdf');

await fetch(`${BASE_URL}/knowledge-bases/${kb.data.id}/documents`, {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY },
  body: formData,
});

#Python

#Basic Request

pythonimport requests

BASE_URL = 'https://your-domain.com/v1'
HEADERS = {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json',
}

# List Agents
resp = requests.get(f'{BASE_URL}/agents', headers=HEADERS)
result = resp.json()
print(f"Found {result['meta']['total']} agents")

#Non-Streaming Chat

pythonresp = requests.post(
    f'{BASE_URL}/agents/{agent_id}/chat',
    headers=HEADERS,
    json={
        'messages': [{'role': 'user', 'content': 'Hello'}],
        'stream': False,
    },
)
print(resp.json()['data']['content'])

#Streaming Chat (SSE)

pythonimport json

resp = requests.post(
    f'{BASE_URL}/agents/{agent_id}/chat',
    headers=HEADERS,
    json={
        'message': 'Analyze current market trends',
        'stream': True,
    },
    stream=True,
)

for line in resp.iter_lines():
    if not line:
        continue
    line = line.decode('utf-8')
    if not line.startswith('data: '):
        continue
    data = line[6:]
    if data == '[DONE]':
        break
    try:
        event = json.loads(data)
        if 'delta' in event:
            print(event['delta'], end='', flush=True)
    except json.JSONDecodeError:
        pass

#cURL

#List Agents

bashcurl -X GET "https://your-domain.com/v1/agents" \
  -H "X-API-Key: your-api-key" \
  -H "X-Project-Id: your-project-id"

#Create Agent

bashcurl -X POST "https://your-domain.com/v1/agents" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "model": "zhipu/glm-4",
    "systemPrompt": "You are a professional customer support assistant."
  }'

#Non-Streaming Chat

bashcurl -X POST "https://your-domain.com/v1/agents/AGENT_ID/chat" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

#Streaming Chat

bashcurl -N -X POST "https://your-domain.com/v1/agents/AGENT_ID/chat" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Tell me about yourself",
    "stream": true
  }'

#Error Handling

All SDK integrations should handle the following scenarios:

401: Invalid or missing API Key — check the X-API-Key header
429: Rate limited — read the Retry-After header and wait
5xx: Server error — implement exponential backoff retry

See the Error Handling documentation for details.