AIsa API Docs Audit Report

Summary Scorecard

Category	Total	✓ Pass	⚠ Warn	✕ Fail
Chat API	5	2	2	1
Video API	2	1	1	0
Search API	5	2	2	1
Perplexity API	4	0	3	1
Scholar API	4	0	2	2
Prediction Market	11	3	8	0
Financial API	22	8	12	2
Twitter Write	6	6	0	0
Twitter Read	25	0	0	25
Total	84	22	30	32

Top Priority Issues

01 ✕ FAIL Twitter Read endpoints (25 pages) — every single one is missing a description and all error response codes. Schemas are solid; prose is nonexistent.

02 ✕ FAIL OpenAI Chat — the highest-traffic page. No response schema, 15+ missing body params (temperature, max_tokens, tools, etc.), description plagiarised from OpenAI's own docs.

03 ✕ FAIL Google Gemini Chat — zero description text, generationConfig is an opaque object with no children, no valid model names listed.

04 ✕ FAIL Segmented Revenues — endpoint is marked deprecated: true in the OpenAPI spec but the page shows zero deprecation warning.

05 ⚠ WARN Response codes missing across 9 endpoints — Search, Perplexity, and Video API pages only document 200. Missing: 400, 401, 429, 500.

06 ⚠ WARN Financial API ticker/cik ambiguity — 6 endpoints mark both as required: false when at least one is always required.

07 ⚠ WARN Scholar API form-body vs query-param ambiguity — query appears in both Query Parameters and form body sections across all 3 search endpoints.

08 ⚠ WARN Perplexity model enum — all 4 Sonar pages list all 4 models in the model field enum instead of their own model only.

09 ⚠ WARN Financial API missing 429 and 500 — consistent gap across all 22 financial pages.

10 ⚠ WARN Tavily Map vs Crawl distinction — no explanation on either page that Map returns URL list only while Crawl returns full page content.

Chat API

5 endpoints 2 pass 2 warn 1 fail

POST /v1/chat/completions OpenAI Chat

▼

Description	✕ FAIL	Copy-pasted verbatim from OpenAI's docs; outbound links point to `platform.openai.com` Fix: Rewrite in AIsa's voice; replace all external OpenAI links with internal guides
OpenAPI Spec	✓ PASS	`openai-chat.json` present
Body Params	✕ FAIL	Only 7 of 20+ params documented. Missing: `temperature`, `max_tokens`, `top_p`, `stop`, `n`, `tools`, `tool_choice`, `response_format`, `presence_penalty`, `frequency_penalty` Fix: Add all standard OpenAI-compatible parameters with descriptions and valid ranges
Response Codes	✕ FAIL	Only `200` documented Add: `400`, `401`, `403`, `422`, `429`, `500`
Response Schema	✕ FAIL	200 response says "Successful completion" with no body defined Add: `id`, `object`, `choices[]`, `usage`, `model`, `finish_reason`

POST /v1/messages Claude Messages

▼

Description	✓ PASS	Clear, references Anthropic spec, notes OpenAI alternative endpoint
OpenAPI Spec	✓ PASS	`claude-messages.json` present
Body Params	✓ PASS	All key params documented with types, ranges and defaults
Response Codes	⚠ WARN	Only `200` Add: `400`, `401`, `403`, `429`, `500`
Response Schema	⚠ WARN	Most fields present; `content[]` children not expanded — only says "text, tool_use, thinking, etc." Fix: Expand content block type schemas

POST /v1/models/{model}:generateContent Google Gemini Chat

▼

Description	✕ FAIL	Zero introductory text on the page Add: Description explaining the native Gemini format and list valid model names
OpenAPI Spec	✓ PASS	`gemini-openapi.json` present
Body Params	✕ FAIL	`generationConfig` and `toolConfig` typed as opaque `object` — no children expanded. No valid model name enum for `{model}` path param Fix: Expand `generationConfig` fields; list valid Gemini model identifiers
Response Codes	✕ FAIL	Only `200` and `default` Add: `400`, `401`, `403`, `429`, `500`
Response Schema	✕ FAIL	Only `candidates[].parts[].text` shown Add: `usageMetadata`, `finishReason`, `safetyRatings`

POST /v1/chat/completions Image Generation via Chat

▼

Description	✓ PASS	Routing table, array-not-string warning, pricing noted
OpenAPI Spec	✓ PASS	`chat-image-generation.json` present
Body Params	✓ PASS	`model`, `messages`, `n` with defaults, ranges, and pricing
Response Codes	⚠ WARN	`200` formally documented; `400`, `404`, `500` mentioned in prose only Fix: Formalise as documented response code entries
Response Schema	✓ PASS	Full schema with `choices[].message.content[].image` and `usage`

POST /v1/images/generations OpenAI-Compatible Image Generations

▼

Description	✓ PASS	Pixel minimum constraint (3,686,400px) clearly documented with table
OpenAPI Spec	✓ PASS	`openai-images-generations.json` present
Body Params	✓ PASS	`model`, `prompt`, `n`, `size` with constraints and pricing
Response Codes	⚠ WARN	`200` formal; `400`, `404` in prose only Fix: Formalise as documented response code entries
Response Schema	✓ PASS	`data[].url`, `data[].size`, `usage` all present

Video API

2 endpoints 1 pass 1 warn

POST /apis/v1/services/aigc/video-generation/video-synthesis Create Video Generation Task

▼

Description	✓ PASS	Model table, `wan2.7-i2v` schema trap warning, required header noted
OpenAPI Spec	✓ PASS	`aliyun-video.json` present
Body Params	✓ PASS	All params documented including `img_url` vs `media` distinction per model
Response Codes	⚠ WARN	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	`task_id`, `task_status`, `request_id` present

GET /apis/v1/services/aigc/tasks/{task_id} Get Video Task Result

▼

Description	✓ PASS	Path-vs-query-string warning prominent; status lifecycle table present
OpenAPI Spec	✓ PASS	`aliyun-video.json` present
Body Params	✓ PASS	`task_id` path param documented; all task states in table
Response Codes	⚠ WARN	Only `200` (always 200 by design) Add: `401`, `500`
Response Schema	⚠ WARN	`output` and `usage` present but children collapsed Expand: `video_url`, `orig_prompt`, `code`, `message`, `submit_time`, `end_time`

Search API

5 endpoints 2 pass 2 warn 1 fail

GET /apis/v1/youtube/search YouTube Search

▼

Description	✕ FAIL	No description at all — just the raw schema Add: Explanation of what YouTube SERP data is returned
OpenAPI Spec	✓ PASS	`youte-search.json` present
Body Params	⚠ WARN	`sp` filter token param has zero explanation Add: Explain `sp`, `gl`, `hl` with valid values
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	⚠ WARN	`search_metadata` is opaque `object` with no children Fix: Expand `search_metadata` children

POST /apis/v1/tavily/search Tavily Search

▼

Description	✓ PASS	Clear and adequate
OpenAPI Spec	✓ PASS	`tavily.json` present
Body Params	⚠ WARN	`search_depth` options (basic/advanced/fast/ultra-fast) lack explanation of differences or cost Add: Description for each depth level and its cost impact
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	Full schema: `query`, `answer`, `images`, `results`, `usage`

POST /apis/v1/tavily/extract Tavily Extract

▼

Description	✓ PASS	Clear and adequate
OpenAPI Spec	✓ PASS	`tavily.json` present
Body Params	✓ PASS	All params with defaults and ranges
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	`results`, `failed_results`, `response_time`, `usage`

POST /apis/v1/tavily/crawl Tavily Crawl

▼

Description	✓ PASS	"Graph-based website traversal tool"
OpenAPI Spec	✓ PASS	`tavily.json` present
Body Params	⚠ WARN	`allow_external: true` default — will follow links off the seed domain with no warning Add: Warning callout about off-domain crawling default behaviour
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	`base_url`, `results`, `response_time`, `usage`

POST /apis/v1/tavily/map Tavily Map

▼

Description	⚠ WARN	Doesn't distinguish from Crawl — no explanation that Map returns URLs only, not page content Add: "Returns URL list only — use Crawl for full page content extraction"
OpenAPI Spec	✓ PASS	`tavily.json` present
Body Params	✓ PASS	All params with defaults and ranges
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	`base_url`, `results[]` (URL strings), `usage`

Perplexity API

4 endpoints 3 warn 1 fail

POST /apis/v1/perplexity/sonar Sonar

▼

Description	✓ PASS	"Lightweight search + answer" — best-for use case clearly noted
OpenAPI Spec	✓ PASS	`perplexity-openapi.json` present
Body Params	⚠ WARN	`model` enum lists all 4 Sonar models — confusing on a Sonar-specific page Fix: Restrict `model` enum to `sonar` only on this page
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	Full schema: `choices`, `citations`, `search_results`, `usage`

POST /apis/v1/perplexity/sonar-pro Sonar Pro

▼

Description	✓ PASS	"Advanced search for complex queries" — best-for noted
OpenAPI Spec	✓ PASS	`perplexity-openapi.json` present
Body Params	⚠ WARN	Same model enum issue — lists all 4 models Fix: Restrict to `sonar-pro` only
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	Full schema present

POST /apis/v1/perplexity/sonar-reasoning-pro Sonar Reasoning Pro

▼

Description	✓ PASS	"Chain-of-thought reasoning with search"
OpenAPI Spec	✓ PASS	`perplexity-openapi.json` present
Body Params	⚠ WARN	Same model enum issue Fix: Restrict to `sonar-reasoning-pro` only
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429`, `500`
Response Schema	✓ PASS	Full schema present

POST /apis/v1/perplexity/sonar-deep-research Sonar Deep Research

▼

Description	⚠ WARN	Latency warning present but missing 5 RPM rate limit note and streaming recommendation Add: Note about 5 RPM cap and recommend streaming for long responses
OpenAPI Spec	✓ PASS	`perplexity-openapi.json` present
Body Params	⚠ WARN	Same model enum issue Fix: Restrict to `sonar-deep-research` only
Response Codes	✕ FAIL	Only `200` Add: `400`, `401`, `429` (5 RPM cap), `500`
Response Schema	✓ PASS	Full schema present

Scholar API

4 endpoints 2 warn 2 fail

POST /apis/v1/scholar/search/scholar Scholar Search

▼

Description	⚠ WARN	No corpus specified — what database does this search? Add: Name the underlying data source (Google Scholar, Semantic Scholar, etc.)
OpenAPI Spec	✓ PASS	`platform-txyz-openapi.json` present
Body Params	✕ FAIL	`query` appears in both Query Parameters section AND form body — ambiguous. Developer can't tell which to use Fix: Clarify: is `query` a query param or a form body field
Response Codes	✓ PASS	`200`, `400`, `401`, `429`, `500` all documented
Response Schema	✓ PASS	Full schema: `id`, `results[]` with title, link, authors, citations, year, journal

POST /apis/v1/scholar/search/web Web Search

▼

Description	⚠ WARN	No differentiation from Tavily Search or Perplexity Add: Explain when to use Scholar Web vs Tavily vs Perplexity
OpenAPI Spec	✓ PASS	`platform-txyz-openapi.json` present
Body Params	✕ FAIL	Same `query` ambiguity as Scholar Search Fix: Clarify parameter location
Response Codes	✓ PASS	`200`, `400`, `401`, `429`, `500`
Response Schema	✓ PASS	Full schema: title, link, snippet, display_url, published_date

POST /apis/v1/scholar/search/mixed Smart Search

▼

Description	⚠ WARN	"Smart" is vague — no explanation of what determines web/academic/hybrid result type Add: Explain when results are classified as web, academic, or hybrid
OpenAPI Spec	✓ PASS	`platform-txyz-openapi.json` present
Body Params	✕ FAIL	Same `query` ambiguity Fix: Clarify parameter location
Response Codes	✓ PASS	`200`, `400`, `401`, `429`, `500`
Response Schema	✓ PASS	`relevance_score`, `search_type` enum present

POST /apis/v1/scholar/search/explain Explain Search Results

▼

Description	⚠ WARN	No mention that `search_id` must come from a prior Scholar call Add: "Requires `search_id` from Scholar Search, Web Search, or Smart Search"
OpenAPI Spec	✓ PASS	`platform-txyz-openapi.json` present
Body Params	⚠ WARN	`language` default is `en` but example value is `ar` — inconsistent Fix: Align example with default or change default
Response Codes	✓ PASS	`200`, `400`, `401`, `404`, `429`, `500`
Response Schema	✓ PASS	Full schema: `explanation`, `summary`, `key_insights`, `confidence_score`

Prediction Market API

11 endpoints 3 pass 8 warn

Pattern across all 11 pages: Descriptions are well-written with curl examples and detailed schemas. The consistent gap is missing 401, 403, 429 response codes. A few specific issues noted below.

GET /apis/v1/polymarket/events Polymarket Events

▼

Description	✓ PASS	Full description with best-for use case, curl example, and pagination explained
OpenAPI Spec	✓ PASS	`polymarket-openapi.json` present
Body Params	✓ PASS	All params fully documented with examples and ranges
Response Codes	✓ PASS	`200`, `400`, `500` documented
Response Schema	✓ PASS	Full schema with events, pagination, and nested markets

GET /apis/v1/polymarket/markets Polymarket Markets

▼

Description	✓ PASS	Comprehensive — volume ordering, search support, filter options explained
OpenAPI Spec	✓ PASS	`polymarket-openapi.json` present
Body Params	✓ PASS	All params fully documented with examples and ranges
Response Codes	⚠ WARN	`200`, `400`, `500` — missing `401`, `429` Add: `401`, `429`
Response Schema	✓ PASS	Full schema with all market fields and pagination

REMAINING PREDICTION MARKET ENDPOINTS — SAME PATTERN

Endpoint	Desc	Spec	Params	Codes	Schema
GET /polymarket/market-price/{token_id}	✓	✓	✓	⚠	✓
GET /polymarket/orderbooks	✓	✓	✓	⚠	✓
GET /polymarket/orders	✓	✓	✓	⚠	✓
GET /polymarket/activity	✓	✓	✓	⚠	✓
GET /polymarket/candlesticks	✓	✓	✓	⚠	✓
GET /polymarket/positions/wallet/{wallet}	✓	✓	✓	⚠	✓
GET /polymarket/wallet	✓	✓	✓	⚠	✓
GET /polymarket/wallet/pnl 503 instead of 500	✓	✓	✓	⚠	✓
GET /kalshi/markets	✓	✓	✓	⚠	✓
GET /kalshi/market-price/{ticker} wrong base URL in example	✓	✓	✓	⚠	✓
GET /kalshi/orderbooks	✓	✓	✓	⚠	✓

⚠ All missing: 401 Unauthorized and 429 Rate Limit response codes. Wallet PnL uses 503 instead of standard 500. Kalshi Market Price examples reference api.domeapi.io instead of api.aisa.one.

Financial API

22 endpoints 8 pass 12 warn 2 fail

Endpoint	Desc	Spec	Params	Codes	Schema	Notes

⚠ All 22 endpoints missing 429 and 500. ❌ Segmented Revenues marked deprecated in spec but no warning on page. ❌ ticker/cik both marked required: false on 6 endpoints — at least one is always required.

Twitter API — Write Actions

6 endpoints 6 pass

All 6 Twitter write endpoints are fully documented — descriptions with OAuth flow, prereqs, scope lists, idempotency notes, 4xx causes, complete response codes (200/400/401/403/404/429/500/502), and full response schemas with examples.

Endpoint	Desc	Spec	Params	Codes	Schema
POST /twitter/auth_twitter	✓	✓	✓	✓	✓
POST /twitter/follow_twitter	✓	✓	✓	✓	✓
POST /twitter/unfollow_twitter	✓	✓	✓	✓	✓
POST /twitter/like_twitter	✓	✓	✓	✓	✓
POST /twitter/unlike_twitter	✓	✓	✓	✓	✓
POST /twitter/post_twitter	✓	✓	✓	✓	✓

Twitter API — Read Endpoints

25 endpoints 25 fail

All 25 read endpoints fail on the same two checks. Schemas are rich and complete. The problem is structural — every page title is a one-liner (e.g., "Get User Info", "Advanced Search") with no prose description, and every page only documents 200 with no error codes.

Endpoint	Desc	Spec	Params	Codes	Schema

❌ All 25 need real descriptions. ❌ All 25 need 400, 401, 429, 500 response codes added.