API Reference

Authorization: Bearer sk_live_01JEXAMPLE...
# or for sandbox / CI:
Authorization: Bearer sk_test_01JEXAMPLE...

curl https://api.skyaiapp.com/v1/route \
  -H "Authorization: Bearer $SKYAIAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_user42_2026-05-14T10:30Z" \
  -d '{
    "goal": "quality",
    "strategy": "quality-first",
    "messages": [
      { "role": "system", "content": "You are a senior travel planner." },
      { "role": "user",   "content": "Plan a 7-day European city-hopping trip in October." }
    ],
    "fallback": {
      "models": ["claude-opus-4.7", "gemini-3.1-pro"],
      "maxRetries": 2
    },
    "budget":     { "maxCostUsd": 0.05 },
    "cache":      true,
    "timeout_ms": 30000,
    "metadata":   { "tenant": "acme-corp", "workflow": "trip-planner", "env": "prod" }
  }'

{
  "trace_id": "tr_01JFGYZ7K8M2N3P4Q5R6S7T8U9",
  "output": "Day 1: Land in Lisbon...",
  "routing": {
    "selected_model":  "gpt-5.5-pro",
    "fallback_chain":  ["claude-opus-4.7", "gemini-3.1-pro"],
    "policy_version":  "policy_prod_v3@2026-05-12",
    "decision_reason": "quality-first + quality goal: gpt-5.5-pro wins on benchmark composite within budget.",
    "cost_usd":        0.0421,
    "latency_ms":      1820,
    "cache_hit":       false,
    "tokens": {
      "input":  256,
      "output": 1840,
      "cached": 0
    }
  },
  "usage": {
    "rate_limit_remaining":  4998,
    "rate_limit_reset_unix": 1715680800
  }
}

curl https://api.skyaiapp.com/v1/models \
  -H "Authorization: Bearer $SKYAIAPP_API_KEY"

{
  "models": [
    {
      "id": "gpt-5.5-pro",
      "provider": "openai",
      "context_window": 1000000,
      "modalities": ["text", "image", "tool"],
      "pricing_per_1m": { "input_usd": 5.00, "output_usd": 30.00 },
      "availability": { "status": "available", "regions": ["us", "eu"] },
      "deprecated_at": null
    },
    { "id": "claude-opus-4.7", "provider": "anthropic", "...": "..." },
    { "id": "gemini-3.1-pro", "provider": "google",    "...": "..." }
  ]
}

curl https://api.skyaiapp.com/v1/agents/run \
  -H "Authorization: Bearer $SKYAIAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Find this month overdue invoices and email a polite reminder to each.",
    "tools": [
      "web_search",
      {
        "name": "lookup_invoice",
        "description": "Fetch invoice by ID from internal billing system.",
        "parameters": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }
      }
    ],
    "max_steps": 10,
    "per_step_timeout_ms": 30000,
    "total_budget_usd": 0.50,
    "model_strategy": { "goal": "quality", "strategy": "balanced" },
    "metadata": { "tenant": "acme-corp", "workflow": "billing-followup" }
  }'

{
  "trace_id": "tr_01JFAGENT2N3P4Q5R6S7T8U9",
  "status": "completed",                       // completed | partial | failed | budget_exceeded
  "output": "Sent reminders to 7 customers; logged failures for 2.",
  "steps": [
    {
      "number": 1,
      "action": "tool_call",
      "tool":   "lookup_invoice",
      "input":  { "id": "inv_2901" },
      "output": { "status": "overdue", "amount_usd": 1820 },
      "duration_ms": 220,
      "cost_usd": 0
    },
    { "number": 2, "action": "llm_call",  "...": "..." }
  ],
  "summary": {
    "total_steps":     9,
    "total_cost_usd":  0.0421,
    "total_latency_ms": 18420,
    "tools_used":      ["lookup_invoice", "send_email"]
  }
}

# Filter on metadata.tenant + only failed traces in the last hour
curl -G https://api.skyaiapp.com/v1/traces \
  -H "Authorization: Bearer $SKYAIAPP_API_KEY" \
  --data-urlencode "from=2026-05-14T09:00:00Z" \
  --data-urlencode "to=2026-05-14T10:00:00Z" \
  --data-urlencode "filter=metadata.tenant=acme-corp,status=failed" \
  --data-urlencode "limit=100"

curl -G https://api.skyaiapp.com/v1/analytics/usage \
  -H "Authorization: Bearer $SKYAIAPP_API_KEY" \
  --data-urlencode "start_date=2026-05-01" \
  --data-urlencode "end_date=2026-05-14" \
  --data-urlencode "group_by=model" \
  --data-urlencode "bucket=day"

X-RateLimit-Limit:        600
X-RateLimit-Remaining:    582
X-RateLimit-Reset:        1715680800     # unix epoch
X-RateLimit-Resource:     requests       # or "tokens"
Retry-After:              4              # seconds; only on 429

{
  "error": {
    "code":     "router.budget_exceeded",
    "message":  "All candidate models exceed budget.maxCostUsd=0.001",
    "type":     "validation_error",
    "request_id": "req_01JFGYZ7K8M2N3P4Q5R6S7T8U9",
    "trace_id":   "tr_01JFGYZ7K8M2N3P4Q5R6S7T8U9",
    "detail": {
      "rejected_candidates": [
        { "model": "gpt-5.5-pro",       "estimated_cost_usd": 0.012 },
        { "model": "claude-opus-4.7",   "estimated_cost_usd": 0.015 }
      ],
      "suggestion": "Increase budget.maxCostUsd or include cheaper models in the policy."
    }
  }
}