πŸ”‘ API Keys

Use API keys to authenticate requests to the Open Source AI Agent API. Keep your keys secret β€” treat them like passwords.

Base URL: https://opensource-ai-agent.uk/api/v1  Β·  Version: v1  Β·  Format: JSON
Generate New API Key
Your API Keys
Plan: loading...
πŸ“Š API Usage This Month
0
Calls Used
1,000
Monthly Limit
60
Calls / Minute
0
Active Keys

πŸ”’ Key Security

Storage

API keys are stored hashed (SHA-256) in our database β€” we cannot recover a lost key. When generated, we show it once. Store it in a password manager or secrets vault immediately.

Rotation

Rotate keys regularly or immediately if you suspect a key has been compromised:

  1. Generate a new key on this page
  2. Update your application to use the new key
  3. Click Revoke on the old key
  4. Verify your application still works

Scopes

ScopeAccessUse case
fullAll endpointsBackend services with full control
readGET onlyRead workflows, fetch results
llm/llm/chat onlyFrontend apps needing AI chat
workflowWorkflow endpointsCI/CD workflow automation

Best Practices

  • Never commit API keys to Git β€” use environment variables
  • Use different keys per environment (dev, staging, production)
  • Use the most restrictive scope that meets your needs
  • Monitor usage in this dashboard for unexpected spikes
  • Revoke keys for team members who leave
Leaked key? Revoke it immediately on this page, then email [email protected] to audit usage. We log all API calls with timestamps and IPs.

Server-side Storage

Keys are stored as SHA-256 hashes in our UK-based database. Raw keys are never stored. Keys are encrypted at rest using AES-256. We log: timestamp, endpoint called, response code, and IP address β€” never request body content.

⚑ Quick Start

Get your first API call working in under 2 minutes.

Base URL: https://opensource-ai-agent.uk  Β·  All responses: JSON  Β·  Auth: Bearer token in header

cURL

Request
# Replace YOUR_API_KEY with your key from above
curl -X POST https://opensource-ai-agent.uk/llm/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"provider":"groq"}'
Response
{
  "text": "Hello! How can I help you today?",
  "provider": "groq",
  "model": "llama3-70b-8192",
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

πŸ” Authentication

All API requests must include your API key in the Authorization header as a Bearer token.

Header
Authorization: Bearer oai_your_key_here
Never include API keys in URLs or client-side JavaScript. Always call from your backend server.

Key format

Keys follow the format oai_ followed by 32 random characters. Example: oai_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

πŸ“‘ Endpoints

Base URL: https://opensource-ai-agent.uk

AI & LLM

MethodEndpointDescriptionPlan
POST/llm/chatChat with AI model (Groq or local 70B)All
POST/api/agent/runRun ReAct reasoning agentPro+
POST/api/ai-buildGenerate workflow from promptAll

Workflows

MethodEndpointDescriptionPlan
GET/api/workflowsList your saved workflowsAll
POST/api/workflowsCreate/save a workflowAll
POST/api/run/workflowExecute a workflowAll
GET/api/executionsExecution historyAll

Data & Integrations

MethodEndpointDescriptionPlan
GET/api/gmail/inboxFetch Gmail inbox (OAuth required)All
GET/api/blockchain/priceCrypto prices (CoinGecko, free)All
GET/api/blockchain/balanceWallet balance on any EVM chainAll
GET/api/pricing/geoLocal pricing by countryAll
POST/api/upload/fileUpload CSV/Excel/JSONAll
POST/api/contactSubmit contact formAll

⚠️ Error Codes

All errors return JSON with a consistent structure:

Error Response
{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 42
}
HTTP StatusCodeMeaningAction
400BAD_REQUESTInvalid request body or parametersCheck your request format
401UNAUTHORIZEDMissing or invalid API keyCheck Authorization header
403FORBIDDENKey does not have required scopeGenerate key with correct scope
404NOT_FOUNDEndpoint or resource does not existCheck endpoint URL
429RATE_LIMIT_EXCEEDEDToo many requestsWait retry_after seconds, then retry
429MONTHLY_LIMIT_EXCEEDEDMonthly call quota reachedUpgrade plan or wait for reset
500INTERNAL_ERRORServer errorRetry with exponential backoff. Contact support if persists.
503SERVICE_UNAVAILABLEMaintenance or overloadRetry after 60 seconds

When you hit your rate limit

We use graceful degradation, not a hard cutoff. When you approach your limit:

  • At 80% of monthly limit β€” warning header added to responses: X-RateLimit-Warning: approaching-limit
  • At 100% β€” requests return 429 with retry_after showing seconds until reset
  • Per-minute limit β€” exponential backoff recommended, retry after retry_after seconds
  • We do not charge overage automatically β€” upgrade your plan to continue

⏱ Rate Limits

PlanPer MinutePer HourPer MonthConcurrent
Community202001,0002
Professional601,00010,00010
Enterprise30010,000Unlimited50
Note on limits: 10,000 calls/month on Pro = ~333/day or ~14/hour. If you're building a real-time chatbot or high-frequency workflow, contact us at [email protected] β€” we can arrange custom limits.

Rate limit headers

Every response includes these headers:

Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1746619200
X-RateLimit-Window: minute

πŸ“Œ API Versioning

The current API version is v1. Version is indicated by the path prefix:

Versioned URL
https://opensource-ai-agent.uk/api/v1/workflows
Currently both /api/v1/ and /api/ resolve to the same endpoints. We recommend using /api/v1/ in production to ensure forward compatibility.

Breaking change policy

  • No breaking changes within a version β€” we add fields, never remove them
  • 90 days notice by email before deprecating any endpoint
  • Both versions run simultaneously for 6 months during transitions
  • Breaking changes always bump the version: v1 β†’ v2
  • Non-breaking additions (new fields, new endpoints) happen without notice

Changelog

VersionDateChanges
v1.0May 2026Initial release β€” LLM chat, workflows, blockchain, Gmail

πŸ“‹ SLA

PlanUptime TargetSupport ResponseIncident Comms
CommunityBest effort2-3 business daysStatus page
Professional99% monthly24 hoursEmail + status page
Enterprise99.5% monthly4 hoursDirect contact + email
We are an early-stage platform. These SLA targets are our commitment, but we are honest that infrastructure is still maturing. Enterprise customers with strict SLA requirements should contact us before subscribing.

Support

  • Email: [email protected]
  • Response times are measured during UK business hours (Mon–Fri, 09:00–17:30 GMT)
  • For billing issues: include your account email and transaction ID

cURL Examples

Chat with AI

cURL
curl -X POST https://opensource-ai-agent.uk/llm/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Summarise this report: ..."}],
    "provider": "groq",
    "max_tokens": 500
  }'
Response
{
  "text": "The report covers...",
  "provider": "groq",
  "model": "llama3-70b-8192",
  "usage": {"prompt_tokens": 45, "completion_tokens": 120, "total_tokens": 165}
}

Get crypto price

cURL
curl "https://opensource-ai-agent.uk/api/blockchain/price?coins=bitcoin,ethereum¤cy=usd" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "success": true,
  "prices": {
    "bitcoin": {"usd": 65432.10, "usd_24h_change": 2.34},
    "ethereum": {"usd": 3456.78, "usd_24h_change": 1.87}
  },
  "currency": "usd"
}

Python Examples

Python β€” pip install requests
import requests

API_KEY = "oai_your_key_here"
BASE_URL = "https://opensource-ai-agent.uk"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Chat with AI
response = requests.post(
    f"{BASE_URL}/llm/chat",
    headers=headers,
    json={
        "messages": [{"role": "user", "content": "Hello"}],
        "provider": "groq",
        "max_tokens": 500
    }
)

data = response.json()
print(data["text"])

# Get crypto prices
prices = requests.get(
    f"{BASE_URL}/api/blockchain/price",
    headers=headers,
    params={"coins": "bitcoin,ethereum", "currency": "usd"}
).json()

print(f"BTC: ${prices['prices']['bitcoin']['usd']:,.2f}")

Error handling

Python β€” with error handling
import requests, time

def chat(message, retries=3):
    for attempt in range(retries):
        r = requests.post(
            "https://opensource-ai-agent.uk/llm/chat",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"messages": [{"role": "user", "content": message}]}
        )
        if r.status_code == 429:
            wait = int(r.json().get("retry_after", 60))
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()["text"]

JavaScript Examples

JavaScript (Node.js or Browser)
const API_KEY = 'oai_your_key_here';
const BASE_URL = 'https://opensource-ai-agent.uk';

// Chat with AI
async function chat(message) {
  const res = await fetch(`${BASE_URL}/llm/chat`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: message }],
      provider: 'groq',
      max_tokens: 500
    })
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error);
  }
  const data = await res.json();
  return data.text;
}

// Get crypto prices
async function getCryptoPrices(coins = ['bitcoin', 'ethereum']) {
  const params = new URLSearchParams({ coins: coins.join(','), currency: 'usd' });
  const res = await fetch(`${BASE_URL}/api/blockchain/price?${params}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  return (await res.json()).prices;
}

// Usage
chat('Explain quantum computing in one paragraph')
  .then(text => console.log(text))
  .catch(err => console.error('Error:', err.message));

Go Example

Go
package main

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

const (
    apiKey  = "oai_your_key_here"
    baseURL = "https://opensource-ai-agent.uk"
)

func chat(message string) (string, error) {
    body, _ := json.Marshal(map[string]interface{}{
        "messages": []map[string]string{{"role": "user", "content": message}},
        "provider": "groq",
    })
    req, _ := http.NewRequest("POST", baseURL+"/llm/chat", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { return "", err }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result["text"].(string), nil
}

func main() {
    text, err := chat("Hello from Go!")
    if err != nil { fmt.Println("Error:", err); return }
    fmt.Println(text)
}