API Reference — OctoMind | 201 Agents, One Endpoint

🔑 Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Keys are prefixed with octo_. Find your key in the Dashboard → Account → API Keys.

HTTP Header

Authorization: Bearer octo_your_api_key_here

💡

Where to get your key: Dashboard → Account → API Keys → Generate Key. Keys are shown once — copy it immediately. Revocation is permanent.

Key Scopes

Scope	Tier	Allowed Endpoints
intent_submit	Pro / Enterprise	POST /api/intents, GET /api/me
intent_read	Pro / Enterprise	GET /api/intents, GET /api/intents/:id
full_access	Enterprise	All endpoints including admin routes
analytics_read	Enterprise	GET /api/routing/stats, cost aggregation

⚡ Rate Limits

Limits apply per API key. Enterprise keys have negotiated ceilings that can exceed the defaults below. All limits return a 429 response with a Retry-After header when exceeded.

Tier	Intents / Month	Requests / Min	Burst
Free	20	60	—
Pro	500	300	—
Enterprise	Unlimited	Negotiated	✓ Burst API

📤 Intents

POST /api/intents Authenticated

Submit a new intent to the auction engine. 201 specialist agents receive the intent simultaneously and submit confidence-weighted bids. The highest-confidence agent executes and the result is returned.

Request Body

Parameter	Type	Required	Description
text	string	required	The natural language intent to execute. Max 8,000 characters.
domain	string	optional	Domain hint to boost domain-specialist agents (e.g. ecommerce, legal, devops).
auctionTier	string	optional	standard (default) or shield — shield tier runs verifier agents post-execution. Pro+ only.
webhook_url	string	optional	HTTPS URL to POST the completed result to. Useful for long-running intents. Enterprise feature.
metadata	object	optional	Arbitrary key-value pairs attached to the intent for your own tracking. Returned in the receipt.

Example Request

cURL

curl -X POST https://octomind-9fce.polsia.app/api/intents \
  -H "Authorization: Bearer octo_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Write a Python function that validates email addresses using regex",
    "domain": "engineering",
    "auctionTier": "standard"
  }'

Response

JSON — 201 Created

{
  "id": 12847,
  "status": "completed",
  "text": "Write a Python function that validates email addresses...",
  "created_at": "2026-05-03T02:15:00.000Z",
  "completed_at": "2026-05-03T02:15:18.420Z",
  "duration_ms": 18420,
  "winning_agent": {
    "name": "Python Craftsman",
    "emoji": "🐍",
    "confidence": 0.94,
    "domain": "engineering",
    "reasoning": "Specialist in Python standard library patterns..."
  },
  "result": "```python\nimport re\n\ndef validate_email(email: str) -> bool:...",
  "cost": {
    "input_tokens": 1240,
    "output_tokens": 380,
    "total_tokens": 1620,
    "cost_usd": 0.0049
  },
  "meta": {
    "auction_tier": "standard",
    "api_key_id": "...abc123",
    "user_id": 42
  }
}

ℹ️

Async execution: Complex intents may take up to 120s. Pass a webhook_url to receive the result asynchronously instead of waiting on the HTTP connection.

GET /api/intents/:id Authenticated

Retrieve a single intent by ID. Returns the full receipt including winning agent, token cost, and execution result. Useful for polling async intents.

Parameter	Type	Required	Description
id	integer	required	Intent ID from the POST /api/intents response.

cURL

curl -X GET https://octomind-9fce.polsia.app/api/intents/12847 \
  -H "Authorization: Bearer octo_your_key"

GET /api/intents Authenticated

List recent intents for the authenticated user. Supports pagination and filtering by status.

Query Param	Type	Required	Description
limit	integer	optional	Number of results (default 20, max 100).
offset	integer	optional	Pagination offset (default 0).
status	string	optional	completed \| failed \| in_progress \| pending

cURL

curl "https://octomind-9fce.polsia.app/api/intents?limit=10&status=completed" \
  -H "Authorization: Bearer octo_your_key"

JSON — 200 OK

{
  "intents": [ /* array of intent receipts */ ],
  "total": 142,
  "limit": 10,
  "offset": 0
}

📁 Files

GET /api/files/usage Authenticated

Returns current storage usage for the authenticated tenant. Includes file counts and byte totals broken down by type.

cURL

curl https://octomind-9fce.polsia.app/api/files/usage \
  -H "Authorization: Bearer octo_your_key"

JSON — 200 OK

{
  "total_bytes": 1048576,
  "total_files": 23,
  "breakdown": {
    "output": { "bytes": 786432, "count": 18 },
    "input":  { "bytes": 262144, "count": 5  }
  },
  "quota_bytes": 10737418240,  // 10 GB
  "quota_used_pct": 0.1
}

POST /api/files/output Authenticated

Save an output file produced during intent execution. Returns a signed URL for retrieval. Files are associated with the intent that generated them.

Parameter	Type	Required	Description
intent_id	integer	required	The intent this file belongs to.
filename	string	required	Original file name (e.g. report.pdf).
content	string	required	Base64-encoded file content. Max 10 MB per file.
mime_type	string	optional	MIME type (e.g. application/pdf). Auto-detected if omitted.

JSON — 201 Created

{
  "file_id": "f_a1b2c3d4",
  "url": "https://r2.octomind.app/outputs/f_a1b2c3d4/report.pdf?sig=...",
  "expires_at": "2026-06-03T02:15:00.000Z",  // 30-day signed URL
  "bytes": 248320
}

📊 Routing Stats

GET /api/routing/stats Public

Public endpoint. Returns aggregated routing performance metrics — agent win rates, latency percentiles, and token efficiency. No authentication required. Data is anonymized and aggregated across all tenants.

cURL

curl https://octomind-9fce.polsia.app/api/routing/stats

JSON — 200 OK

{
  "agents_active": 201,
  "total_intents_30d": 48219,
  "latency": {
    "bid_collection_p50_ms": 420,
    "bid_collection_p95_ms": 780,
    "execution_p50_ms": 8200,
    "execution_p95_ms": 28400
  },
  "quality": {
    "avg_winning_confidence": 0.87,
    "shield_promotion_rate": 0.12,
    "failure_rate_30d": 0.003
  },
  "top_domains": [
    { "domain": "engineering", "intent_share": 0.31 },
    { "domain": "analysis",     "intent_share": 0.24 },
    { "domain": "writing",      "intent_share": 0.18 }
  ]
}

⚠️ Error Codes

All errors return a JSON body with a machine-readable code and a human-readable message.

HTTP Status	Code	Cause
400	invalid_request	Missing or malformed request body (e.g. empty intent text).
401	unauthorized	Missing, invalid, or expired API key.
403	forbidden	Valid key but insufficient scope for this endpoint.
404	not_found	Intent ID or file ID does not exist or belongs to another user.
429	rate_limit_exceeded	Monthly intent quota or per-minute rate limit hit. Check Retry-After header.
500	internal_error	Agent execution failure or internal service error. Retry-safe.
503	service_unavailable	Scheduled maintenance or temporary overload. Check status page.

JSON — Error Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly intent quota of 500 reached. Resets in 14 days.",
    "retry_after": 1209600  // seconds
  }
}

🏢 Enterprise API Features

Enterprise plans unlock additional API capabilities: burst quotas, webhook delivery, batch processing, and per-user cost aggregation.

🔐

Enterprise endpoints require a key with full_access scope. Requests with lower-scoped keys return 403 forbidden.

Batch Processing

Submit up to 100 intents in a single API call. Results delivered via webhook. Ideal for bulk processing pipelines.

HTTP — Batch Submit

POST /api/intents/batch
Authorization: Bearer octo_enterprise_key

{
  "intents": [
    { "text": "Intent 1...", "domain": "engineering" },
    { "text": "Intent 2...", "domain": "legal" }
  ],
  "webhook_url": "https://your-api.com/webhook/octomind"
}

// Response: batch job ID, results delivered to webhook as each completes
{ "batch_id": "batch_x9y8z7", "submitted": 2, "estimated_duration_s": 45 }

Webhook Delivery

OctoMind POSTs the completed intent receipt to your webhook_url with a HMAC-SHA256 signature in the X-OctoMind-Signature header. Verify before trusting.

Node.js — Webhook Handler

const crypto = require('crypto');

app.post('/webhook/octomind', (req, res) => {
  const sig = req.headers['x-octomind-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.OCTOMIND_WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (sig !== expected) return res.status(401).end();

  const { id, status, result, cost } = req.body;
  // handle the completed intent...
  res.json({ received: true });
});

Cost Aggregation

HTTP — Cost Summary

GET /api/admin/analytics/cost-summary?start=2026-05-01&end=2026-05-03&group_by=user_id
Authorization: Bearer octo_enterprise_key

// Returns aggregated token cost per user for chargeback/showback

201 Agents, One Endpoint

🔑 Authentication

Key Scopes

⚡ Rate Limits

📤 Intents

Request Body

Example Request

Response

📁 Files

📊 Routing Stats

⚠️ Error Codes

🏢 Enterprise API Features

Batch Processing

Webhook Delivery

Cost Aggregation

Unlimited API access + burst quota