π API Keys
Use API keys to authenticate requests to the Open Source AI Agent API. Keep your keys secret β treat them like passwords.
https://opensource-ai-agent.uk/api/v1 Β·
Version: v1 Β·
Format: JSON
π 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:
- Generate a new key on this page
- Update your application to use the new key
- Click Revoke on the old key
- Verify your application still works
Scopes
| Scope | Access | Use case |
|---|---|---|
| full | All endpoints | Backend services with full control |
| read | GET only | Read workflows, fetch results |
| llm | /llm/chat only | Frontend apps needing AI chat |
| workflow | Workflow endpoints | CI/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
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.
https://opensource-ai-agent.uk Β· All responses: JSON Β· Auth: Bearer token in headercURL
# 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"}'
{
"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.
Authorization: Bearer oai_your_key_here
Key format
Keys follow the format oai_ followed by 32 random characters. Example: oai_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
π‘ Endpoints
https://opensource-ai-agent.ukAI & LLM
| Method | Endpoint | Description | Plan |
|---|---|---|---|
| POST | /llm/chat | Chat with AI model (Groq or local 70B) | All |
| POST | /api/agent/run | Run ReAct reasoning agent | Pro+ |
| POST | /api/ai-build | Generate workflow from prompt | All |
Workflows
| Method | Endpoint | Description | Plan |
|---|---|---|---|
| GET | /api/workflows | List your saved workflows | All |
| POST | /api/workflows | Create/save a workflow | All |
| POST | /api/run/workflow | Execute a workflow | All |
| GET | /api/executions | Execution history | All |
Data & Integrations
| Method | Endpoint | Description | Plan |
|---|---|---|---|
| GET | /api/gmail/inbox | Fetch Gmail inbox (OAuth required) | All |
| GET | /api/blockchain/price | Crypto prices (CoinGecko, free) | All |
| GET | /api/blockchain/balance | Wallet balance on any EVM chain | All |
| GET | /api/pricing/geo | Local pricing by country | All |
| POST | /api/upload/file | Upload CSV/Excel/JSON | All |
| POST | /api/contact | Submit contact form | All |
β οΈ Error Codes
All errors return JSON with a consistent structure:
{
"success": false,
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"retry_after": 42
}
| HTTP Status | Code | Meaning | Action |
|---|---|---|---|
| 400 | BAD_REQUEST | Invalid request body or parameters | Check your request format |
| 401 | UNAUTHORIZED | Missing or invalid API key | Check Authorization header |
| 403 | FORBIDDEN | Key does not have required scope | Generate key with correct scope |
| 404 | NOT_FOUND | Endpoint or resource does not exist | Check endpoint URL |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests | Wait retry_after seconds, then retry |
| 429 | MONTHLY_LIMIT_EXCEEDED | Monthly call quota reached | Upgrade plan or wait for reset |
| 500 | INTERNAL_ERROR | Server error | Retry with exponential backoff. Contact support if persists. |
| 503 | SERVICE_UNAVAILABLE | Maintenance or overload | Retry 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_aftershowing seconds until reset - Per-minute limit β exponential backoff recommended, retry after
retry_afterseconds - We do not charge overage automatically β upgrade your plan to continue
β± Rate Limits
| Plan | Per Minute | Per Hour | Per Month | Concurrent |
|---|---|---|---|---|
| Community | 20 | 200 | 1,000 | 2 |
| Professional | 60 | 1,000 | 10,000 | 10 |
| Enterprise | 300 | 10,000 | Unlimited | 50 |
Rate limit headers
Every response includes these 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:
https://opensource-ai-agent.uk/api/v1/workflows
/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
| Version | Date | Changes |
|---|---|---|
| v1.0 | May 2026 | Initial release β LLM chat, workflows, blockchain, Gmail |
π SLA
| Plan | Uptime Target | Support Response | Incident Comms |
|---|---|---|---|
| Community | Best effort | 2-3 business days | Status page |
| Professional | 99% monthly | 24 hours | Email + status page |
| Enterprise | 99.5% monthly | 4 hours | Direct contact + email |
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 -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
}'
{
"text": "The report covers...",
"provider": "groq",
"model": "llama3-70b-8192",
"usage": {"prompt_tokens": 45, "completion_tokens": 120, "total_tokens": 165}
}
Get crypto price
curl "https://opensource-ai-agent.uk/api/blockchain/price?coins=bitcoin,ethereum¤cy=usd" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"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
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
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
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
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) }