Casca AI Route — API Documentation

Authentication

All API endpoints require a Casca API key. Pass it as a Bearer token in the Authorization header.

🔑 API Key Auth

API keys start with csk_ and are generated in your dashboard at cascaio.com/dashboard.

Authorization: Bearer csk_your_api_key_here

Error Codes

Status	Meaning
200	Success
400	Bad Request — missing required field (check error message)
401	Unauthorized — invalid or missing API key
402	Payment Required — token quota exhausted, top up credits
500	Internal routing error — retry or contact support

GET /api/zapier/auth-test

Verify API Key

Validates an API key and returns account information. Zapier calls this endpoint automatically when a user connects their account.

Request

Header	Value
Authorization	required `Bearer csk_...`

Response 200

{
  "id":           "uuid-of-account",
  "email":        "user@company.com",
  "company_name": "ACME Corp",
  "plan":         "Starter",
  "label":        "ACME Corp"  // used by Zapier as connection label
}

Response 401

{ "error": "Invalid or inactive API key." }

POST /api/zapier/chat

AI Chat

Send any prompt to Casca. The engine automatically classifies complexity (LOW / MED / HIGH) and routes to the optimal model — balancing cost and quality.

Request Body (JSON)

Field	Type	Description
prompt	string	required The user message to send to AI.
system_prompt	string	optional System instructions. Example: "You are a customer service agent. Be concise."
use_case	string	optional Hint for routing accuracy. One of: `GENERAL` `CASE_SUMMARY` `SOQL_GEN` `TRANSLATION` `CODE_GEN` `FIELD_ENRICH`
temperature	number	optional Creativity level 0.0–2.0. Default: `0.7`
max_tokens	integer	optional Max response length in tokens. Default: `2048`

Example Request

curl -X POST https://api.cascaio.com/api/zapier/chat \
  -H "Authorization: Bearer csk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize this email: The Q3 results show...",
    "use_case": "CASE_SUMMARY"
  }'

Response 200

{
  "id":             "chatcmpl-abc123",
  "content":        "Q3 results highlight a 15% growth in revenue...",
  "model":          "gpt-4o-mini",
  "classification": "LOW",       // LOW | MED | HIGH | CACHE
  "tokens_used":    142,
  "cost_usd":       0.0000213,
  "savings_pct":    97,           // % saved vs GPT-4o baseline
  "cache_hit":      false,
  "latency_ms":     1240
}

Response 400

{ "error": "prompt is required." }

POST /api/zapier/summarize

Summarize Text

Summarize any text into concise bullet points. Internally routes through Casca's optimized LOW-complexity path for maximum cost efficiency.

Request Body (JSON)

Field	Type	Description
text	string	required The text to summarize.
language	string	optional Output language. Default: `English`
bullet_points	integer	optional Number of bullet points. Default: `5`

Response 200

Note: Returns the same schema as /api/zapier/chat. The content field contains the bullet-point summary.

{
  "id":          "chatcmpl-xyz789",
  "content":     "• Revenue grew 15% YoY\n• New markets in APAC\n• ...",
  "model":       "gemini-flash",
  "tokens_used": 198,
  "cost_usd":    0.0000049,
  "savings_pct": 97,
  "cache_hit":   false,
  "latency_ms":  890
}

POST /api/zapier/translate

Translate Text

Translate text to any target language. Returns only the translated content with no explanation.

Request Body (JSON)

Field	Type	Description
text	string	required The text to translate.
target_language	string	required Target language. Example: `Traditional Chinese`, `Japanese`, `French`

Response 200

{
  "id":          "chatcmpl-tr001",
  "content":     "這是一個測試句子。",
  "model":       "gemini-flash",
  "tokens_used": 28,
  "cost_usd":    0.0000007,
  "savings_pct": 97,
  "cache_hit":   false,
  "latency_ms":  620
}

POST /api/zapier/generate-soql

Generate SOQL Query

Convert a natural language question into a Salesforce SOQL query. Returns only the query string with no explanation.

Request Body (JSON)

Field	Type	Description
query	string	required Natural language question. Example: "Find all contacts in the Technology industry created this year"
objects	string	optional Available Salesforce objects. Default: `Standard Objects`

Response 200

{
  "id":          "chatcmpl-sq001",
  "content":     "SELECT Id, Name, Email FROM Contact WHERE Industry = 'Technology' AND CreatedDate = THIS_YEAR",
  "model":       "gpt-4o-mini",
  "tokens_used": 87,
  "cost_usd":    0.0000131,
  "savings_pct": 85,
  "cache_hit":   false,
  "latency_ms":  980
}

GET /api/zapier/logs

New API Request (Trigger)

Polling trigger — returns recent API request logs. Zapier polls this endpoint every 1–15 minutes and fires the Zap when new log entries appear.

Query Parameters

Parameter	Type	Description
limit	integer	optional Max records to return (1–100). Default: `25`

Response 200 — Array

[
  {
    "id":           "log-uuid-001",       // unique ID (required by Zapier)
    "prompt_hash":  "a1b2c3d4e5f6...",
    "cx":           "LOW",                 // LOW | MED | HIGH | CACHE
    "model_name":   "gpt-4o-mini",
    "tokens_in":    42,
    "tokens_out":   128,
    "cost_usd":     0.000025,
    "savings_pct":  85,
    "is_cache_hit": false,
    "latency_ms":   1200,
    "status_code":  200,
    "created_at":   "2026-04-07T10:00:00Z"
  }
]

GET /api/zapier/annotations

New Annotation (Trigger)

Polling trigger — returns pending annotation queue items. Fires when Casca detects an ambiguous classification that needs human review.

Response 200 — Array

[
  {
    "id":             "ann-uuid-001",
    "prompt":         "What is the cancellation policy?",
    "predicted_cx":   "MED",
    "triggered_rule": "AMBIG_DETECT",
    "lang":           "EN",
    "uc":             "GENERAL",
    "status":         "pending",
    "created_at":     "2026-04-07T10:05:00Z"
  }
]

GET /api/zapier/usage

Usage Quota Alert (Trigger)

Polling trigger — fires when token usage exceeds 80% of plan quota. Returns at most one alert per account per day (deduplicated by date-based ID).

Note: Returns an empty array [] when usage is below 80% — Zapier will not fire the Zap in that case.

Response 200 — Array (when usage ≥ 80%)

[
  {
    "id":               "usage-uuid-2026-04-07",   // unique per account per day
    "email":            "user@company.com",
    "plan":             "Starter",
    "used_tokens":      8500000,
    "included_tokens":  10000000,
    "usage_pct":        85,
    "balance_credits":  25.50,
    "alert_level":      "WARNING",    // WARNING (80-99%) | OVER_QUOTA (100%+)
    "date":             "2026-04-07"
  }
]

Response 200 — Empty (usage < 80%)

[]