{"openapi":"3.1.0","info":{"title":"Nicezest Intelligence API","version":"1.0.0","description":"The Nicezest Intelligence API provides programmatic access to structured, verified, evidence-backed AI product intelligence, foundation models, ecosystem taxonomies, and temporal change ledgers.","contact":{"name":"Nicezest Developer Support","url":"https://www.nicezest.com/developers"}},"servers":[{"url":"https://www.nicezest.com","description":"Production API Gateway"},{"url":"http://localhost:3000","description":"Local Development Gateway"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"paths":{"/api/v1/tools":{"get":{"summary":"Search & Discover AI Products","description":"Query canonical AI product intelligence records with multi-dimensional filtering, verification checks, and bounded pagination.","parameters":[{"name":"q","in":"query","description":"Search keyword across name, tagline, description, slug","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category name/vertical","schema":{"type":"string"}},{"name":"company","in":"query","description":"Filter by company slug","schema":{"type":"string"}},{"name":"status","in":"query","description":"Tool lifecycle status (active, candidate)","schema":{"type":"string","enum":["active","candidate","verified"]}},{"name":"verification_status","in":"query","description":"Verification state (verified, pending)","schema":{"type":"string","enum":["verified","pending"]}},{"name":"is_open_source","in":"query","description":"Filter by open source status","schema":{"type":"string","enum":["true","false"]}},{"name":"tool_type","in":"query","description":"Tool classification","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size limit (1-100, default 20)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"Pagination offset (default 0)","schema":{"type":"integer","default":0,"minimum":0}},{"name":"sort","in":"query","description":"Sorting strategy","schema":{"type":"string","enum":["score","newest","name"],"default":"score"}}],"responses":{"200":{"description":"Successful paginated tools query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedToolsResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/api/v1/tools/{slug}":{"get":{"summary":"Get Product Intelligence Dossier","description":"Retrieve the comprehensive verified intelligence dossier for a single AI product including scores, pricing plans, models, features, health, and recent changes.","parameters":[{"name":"slug","in":"path","required":true,"description":"Canonical product slug (e.g., \"cursor\")","schema":{"type":"string"}}],"responses":{"200":{"description":"Product dossier retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDossierResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/api/v1/tools/{slug}/history":{"get":{"summary":"Query Tool Change History","description":"Retrieve chronological historical change events and evidence records from the temporal intelligence ledger for a specific product.","parameters":[{"name":"slug","in":"path","required":true,"description":"Canonical product slug","schema":{"type":"string"}},{"name":"from","in":"query","description":"ISO 8601 start timestamp filter","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"ISO 8601 end timestamp filter","schema":{"type":"string","format":"date-time"}},{"name":"change_type","in":"query","description":"Filter by change type (pricing_changed, model_added, feature_added, major_release)","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page limit (1-100, default 20)","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","description":"Offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Historical events retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedHistoryResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/api/v1/categories":{"get":{"summary":"Get Category Taxonomy","description":"Retrieve the public hierarchical AI category taxonomy.","parameters":[{"name":"parent","in":"query","description":"Filter by parent category","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Categories taxonomy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCategoriesResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/api/v1/models":{"get":{"summary":"Get Foundation Model Catalog","description":"Retrieve the public foundation AI models catalog with context window sizes, token pricing, and verified capability tags.","parameters":[{"name":"provider","in":"query","description":"Filter by provider (e.g. Anthropic, OpenAI)","schema":{"type":"string"}},{"name":"capability","in":"query","description":"Filter by capability tag (e.g. code_generation, reasoning)","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Models catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedModelsResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}},"/api/v1/changes":{"get":{"summary":"Query Ecosystem Change Events","description":"Query verified temporal change events across the entire AI ecosystem.","parameters":[{"name":"tool","in":"query","description":"Filter by tool slug","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category","schema":{"type":"string"}},{"name":"change_type","in":"query","description":"Filter by change type","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Ecosystem change events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedChangesResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitedError"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key (nz_live_...)","description":"Provide your Nicezest API key via the standard Authorization: Bearer <API_KEY> header."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative header: x-api-key: <API_KEY>"}},"responses":{"UnauthorizedError":{"description":"Authentication failed or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UNAUTHORIZED","message":"Missing or invalid API key. Provide Authorization: Bearer <API_KEY>."}}}}},"NotFoundError":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"NOT_FOUND","message":"Product with slug \"non-existent\" was not found."}}}}},"RateLimitedError":{"description":"Per-minute API quota exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Maximum 60 requests per minute allowed on this key tier."}}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","RATE_LIMITED","INVALID_REQUEST","INTERNAL_ERROR"]},"message":{"type":"string"}}}}},"PaginationMeta":{"type":"object","required":["limit","offset","total","has_more"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"PaginatedToolsResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"ToolDossierResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}},"PaginatedHistoryResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedCategoriesResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedModelsResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"PaginatedChangesResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}