Create Integration

Add a new API key for an LLM provider to your brand's key pool.

Request

POST /api/v1/integrations

Headers

Header	Value	Required
Authorization	Bearer {client_token}	Yes
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
provider_name	string	Yes	Provider identifier (see supported providers below)
credentials	object	Yes	Provider-specific credentials (e.g., {"api_key": "sk-..."})
key_label	string	No	Friendly name for identification
is_primary	boolean	No	Primary keys are selected first (default: false)
daily_limit	integer	No	Maximum requests per day
minute_limit	integer	No	Maximum requests per minute
spend_limit_amount	decimal	No	Spend alert threshold in USD
spend_limit_period	string	No	daily or monthly (default: monthly)
spend_limit_action	string	No	warn or block (default: warn)

Supported Providers

Provider Name	Credential Format
openrouter	{"api_key": "sk-or-v1-..."}
groq	{"api_key": "gsk_..."}
mistral	{"api_key": "..."}
google_ai	{"api_key": "AIza..."}
fal_ai	{"api_key": "fal_..."}
cerebras	{"api_key": "csk-..."}
together	{"api_key": "..."}
cohere	{"api_key": "..."}
cloudflare	{"api_key": "...", "account_id": "..."}
nvidia_nim	{"api_key": "nvapi-..."}
fireworks	{"api_key": "fw_..."}
sambanova	{"api_key": "..."}
huggingface	{"api_key": "hf_..."}
github_models	{"api_key": "ghp_..."}
ai21	{"api_key": "..."}
baseten	{"api_key": "..."}

Example Request

curl -X POST "https://spideriq.ai/api/v1/integrations" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "openrouter",
    "credentials": {
      "api_key": "sk-or-v1-abc123..."
    },
    "key_label": "Production OpenRouter",
    "is_primary": true,
    "daily_limit": 10000,
    "minute_limit": 100,
    "spend_limit_amount": 500.00,
    "spend_limit_period": "monthly",
    "spend_limit_action": "warn"
  }'

Response

Success (201 Created)

{
  "success": true,
  "integration": {
    "id": 42,
    "provider_name": "openrouter",
    "provider_label": "OpenRouter",
    "key_label": "Production OpenRouter",
    "is_active": true,
    "is_primary": true,
    "priority": 10,
    "daily_limit": 10000,
    "daily_count": 0,
    "minute_limit": 100,
    "minute_count": 0,
    "health_status": "healthy",
    "consecutive_failures": 0,
    "spend_limit_amount": 500.00,
    "spend_limit_period": "monthly",
    "spend_limit_action": "warn",
    "spend_limit_exceeded": false,
    "key_preview": {
      "api_key": "sk-o...123"
    },
    "created_at": "2026-02-26T15:00:00Z"
  }
}

Error Responses

400 Bad Request - Invalid provider or credentials format

{
  "success": false,
  "error": "Invalid provider_name. Supported: openrouter, groq, mistral, ..."
}

409 Conflict - Duplicate key

{
  "success": false,
  "error": "A key with this credential already exists for this provider"
}

Notes

• API keys are encrypted with Fernet symmetric encryption before storage
• key_preview shows a masked version for identification
• Primary keys (is_primary: true) get priority: 10, others get priority: 0
• Health status starts as healthy and is updated based on usage success/failure