ResourcesQuick Reference

Quick Reference Guide

Table of Contents

Authentication

Register Account

curl -X POST https://api.polysystems.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass123!", "username": "myuser"}'

Login

curl -X POST https://api.polysystems.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass123!"}'

Response: JWT token (valid 24 hours)

Access Token Management

Generate Access Token

curl -X POST https://api.polysystems.ai/api/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Key"}'

⚠️ Save the key_value immediately - shown only once!

List Access Tokens

curl -X GET https://api.polysystems.ai/api/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Revoke Token

curl -X POST https://api.polysystems.ai/api/keys/{key_id}/revoke \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete Token

curl -X DELETE https://api.polysystems.ai/api/keys/{key_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Making API Calls

Two Ways to Authenticate

Method 1: X-API-Key Header (Recommended)

curl -X POST https://api.polysystems.ai/api/hub/agents/chat \
  -H "X-API-Key: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Method 2: Authorization Bearer

curl -X POST https://api.polysystems.ai/api/hub/agents/chat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Payment & Credits

Check Balance

curl -X GET https://api.polysystems.ai/api/payments/credits/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create Payment (x402)

curl -X POST https://api.polysystems.ai/api/payments/payments \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 50.00, "currency": "ETH"}'

Supported Currencies: BTC, ETH, SOL

Check Payment Status

curl -X GET https://api.polysystems.ai/api/payments/payments/{payment_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

List Transactions

curl -X GET https://api.polysystems.ai/api/payments/transactions?limit=10 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Spending Limits

Set Spending Limits

curl -X PUT https://api.polysystems.ai/api/keys/{key_id}/limits \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_limit": 10.00,
    "monthly_limit": 250.00,
    "per_request_limit": 1.00
  }'

Get Limits

curl -X GET https://api.polysystems.ai/api/keys/{key_id}/limits \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Reset Spending Counters

curl -X POST https://api.polysystems.ai/api/keys/{key_id}/limits/reset \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Remove All Limits

curl -X DELETE https://api.polysystems.ai/api/keys/{key_id}/limits \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Codes

CodeStatusCommon CauseSolution
400Bad RequestInvalid request formatCheck request body/params
401UnauthorizedMissing/invalid API keyCheck authentication
402Payment RequiredInsufficient creditsAdd credits or check limits
403ForbiddenNo permissionCheck account permissions
404Not FoundResource doesn’t existVerify resource ID
429Too Many RequestsRate limit exceededSlow down, check Retry-After header
500Internal Server ErrorServer issueRetry with backoff
503Service UnavailableTemporary outageRetry later

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 1000          # Total allowed in window
X-RateLimit-Remaining: 999       # Requests remaining
X-RateLimit-Reset: 1705327200    # Unix timestamp when resets
X-RateLimit-Window: 3600         # Window in seconds

Default Limits

TierRequests/SecondRequests/MinuteRequests/Hour
Free110100
Basic51001,000
Pro201,00010,000
EnterpriseCustomCustomCustom

Handle Rate Limit Errors

import time
import requests
 
response = requests.post(url, headers=headers, json=data)
 
if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)
    # Retry request

Common Endpoints

Health Check (Public)

curl https://api.polysystems.ai/api/hub/health

Chat Completion

curl -X POST https://api.polysystems.ai/api/hub/agents/chat \
  -H "X-API-Key: YOUR_TOKEN" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are helpful."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Store Memory

curl -X POST https://api.polysystems.ai/api/hub/memory \
  -H "X-API-Key: YOUR_TOKEN" \
  -d '{
    "key": "user_pref",
    "value": "dark_mode",
    "metadata": {"user_id": "123"}
  }'

Search Memory

curl -X POST https://api.polysystems.ai/api/hub/memory/search \
  -H "X-API-Key: YOUR_TOKEN" \
  -d '{"query": "user preferences", "limit": 10}'

Submit Task

curl -X POST https://api.polysystems.ai/api/hub/tasks \
  -H "X-API-Key: YOUR_TOKEN" \
  -d '{
    "task_type": "data_processing",
    "parameters": {"input": "data.csv"},
    "priority": "high"
  }'

Get Task Status

curl -X GET https://api.polysystems.ai/api/hub/tasks/{task_id} \
  -H "X-API-Key: YOUR_TOKEN"

RAG - Index Document

curl -X POST https://api.polysystems.ai/api/hub/rag/index \
  -H "X-API-Key: YOUR_TOKEN" \
  -d '{
    "content": "Document content here...",
    "metadata": {"title": "My Document"}
  }'

RAG - Generate with Context

curl -X POST https://api.polysystems.ai/api/hub/rag/generate \
  -H "X-API-Key: YOUR_TOKEN" \
  -d '{"query": "What is...?", "top_k": 5}'

Pricing Quick Reference

Base Prices (USD)

Endpoint TypeBase PriceToken PriceExample Cost
Memory Operations$0.0001N/A$0.0001
Chat Completion$0.0020$0.00001/token0.0020−0.0020 - 0.05
RAG Generation$0.0030$0.00001/token0.0030−0.0030 - 0.10
OMM Processing$0.0030$0.00002/token0.0030−0.0030 - 0.10
Legal Analysis$0.0050$0.00003/token0.0050−0.0050 - 0.15

Cost Headers

X-Request-Cost: 0.0035           # Cost of this request
X-Tokens-Used: 150               # Tokens processed
X-Balance-Remaining: 47.2915     # Remaining balance

Environment Variables

# Required
export PS_API_KEY="ps_live_your_access_token"
 
# Optional
export PS_API_URL="https://api.polysystems.ai"
export PS_JWT_TOKEN="your_jwt_token"

Code Snippets

Python

import os
import requests
 
API_KEY = os.getenv('PS_API_KEY')
BASE_URL = "https://api.polysystems.ai"
 
def chat(message):
    response = requests.post(
        f"{BASE_URL}/api/hub/agents/chat",
        headers={'X-API-Key': API_KEY, 'Content-Type': 'application/json'},
        json={'messages': [{'role': 'user', 'content': message}]}
    )
    return response.json()
 
result = chat("Hello!")
print(result)

Node.js

const axios = require('axios');
 
const API_KEY = process.env.PS_API_KEY;
const BASE_URL = 'https://api.polysystems.ai';
 
async function chat(message) {
  const response = await axios.post(
    `${BASE_URL}/api/hub/agents/chat`,
    { messages: [{ role: 'user', content: message }] },
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}
 
chat('Hello!').then(console.log);

cURL with Environment Variable

curl -X POST https://api.polysystems.ai/api/hub/agents/chat \
  -H "X-API-Key: $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Best Practices Checklist

Security

  • ✅ Never hardcode API keys
  • ✅ Use environment variables or secrets manager
  • ✅ Rotate keys every 90 days
  • ✅ Use different keys for dev/staging/prod
  • ✅ Set spending limits on all tokens

Performance

  • ✅ Implement response caching
  • ✅ Use connection pooling
  • ✅ Batch operations when possible
  • ✅ Handle rate limits gracefully
  • ✅ Implement request deduplication

Cost Optimization

  • ✅ Optimize prompts to reduce tokens
  • ✅ Set max_tokens limits
  • ✅ Cache frequent queries
  • ✅ Use batch endpoints
  • ✅ Monitor spending daily

Error Handling

  • ✅ Wrap all API calls in try-catch
  • ✅ Implement exponential backoff
  • ✅ Log errors with context
  • ✅ Handle all HTTP status codes
  • ✅ Provide user-friendly error messages

Monitoring

  • ✅ Log all API requests
  • ✅ Track costs and usage
  • ✅ Set up balance alerts
  • ✅ Monitor rate limit usage
  • ✅ Implement health checks

Common Issues

”Invalid API key”

  • Check key is correct (no typos)
  • Verify key is still active
  • Confirm key hasn’t expired
  • Try regenerating key

”Insufficient credits”

  • Check balance: /api/payments/credits/balance
  • Add credits via x402 payment
  • Verify payment was confirmed

”Spending limit exceeded”

  • Check limits: /api/keys/{key_id}/limits
  • Wait for daily/monthly reset
  • Increase limits or use different token

”Rate limit exceeded”

  • Check rate limit headers
  • Implement exponential backoff
  • Reduce request frequency
  • Consider upgrading tier

Support

Useful Links

Last Updated: 2024-01-15

Best Practices