{ "openapi": "3.1.0", "info": { "title": "AI 24 Updates Public API", "version": "1", "description": "Read-only public API for verified AI news published every two hours. All endpoints return published content only. No authentication required.", "contact": { "email": "ai24updates@gmail.com" }, "license": { "name": "All rights reserved" } }, "servers": [ { "url": "https://ai24updates.com", "description": "Production" } ], "paths": { "/api/v1/issues": { "get": { "summary": "List published issues", "description": "Returns a paginated list of published issues in reverse chronological order.", "operationId": "listIssues", "tags": ["Issues"], "parameters": [ { "name": "limit", "in": "query", "description": "Number of issues to return. Min 1, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "ISO 8601 UTC timestamp from a previous response's `next_cursor`. Fetches the next page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "date", "in": "query", "description": "Filter to issues scheduled on a Budapest calendar date (YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-11-01" } } ], "responses": { "200": { "description": "Paginated list of issues", "content": { "application/json": { "schema": { "type": "object", "required": ["issues", "has_more"], "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/IssueSummary" } }, "next_cursor": { "type": "string", "format": "date-time", "nullable": true }, "has_more": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/issues/{slug}": { "get": { "summary": "Get a single issue", "description": "Returns a published issue with all its updates, sources, and facts.", "operationId": "getIssue", "tags": ["Issues"], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Issue slug (lowercase letters, digits, hyphens).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "example": "2026-11-01-00-00" } } ], "responses": { "200": { "description": "Issue with full update content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/updates": { "get": { "summary": "List individual updates", "description": "Returns a paginated list of individual news updates across all published issues, newest first.", "operationId": "listUpdates", "tags": ["Updates"], "parameters": [ { "name": "limit", "in": "query", "description": "Number of updates to return. Min 1, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Compound cursor from a previous response's `next_cursor` (`__`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of updates", "content": { "application/json": { "schema": { "type": "object", "required": ["updates", "has_more"], "properties": { "updates": { "type": "array", "items": { "$ref": "#/components/schemas/Update" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/search": { "get": { "summary": "Full-text search across updates", "description": "Searches update titles, summaries, and facts using PostgreSQL full-text search. Returns updates from published issues only.", "operationId": "searchUpdates", "tags": ["Search"], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query. Max 200 characters. Supports websearch syntax (AND, OR, phrase, negation).", "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "description": "Number of results to return. Min 1, max 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "description": "Compound cursor from a previous response's `next_cursor`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results with query echo", "content": { "application/json": { "schema": { "type": "object", "required": ["results", "has_more", "query"], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Update" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" }, "query": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "schemas": { "Source": { "type": "object", "required": ["label", "url"], "properties": { "label": { "type": "string", "description": "Human-readable source name" }, "url": { "type": "string", "format": "uri", "description": "Primary source URL" } } }, "Update": { "type": "object", "required": ["id", "title", "summary", "facts", "sources", "issue_slug", "issue_scheduled_at", "issue_url", "url"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "summary": { "type": "string" }, "facts": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "issue_slug": { "type": "string" }, "issue_scheduled_at": { "type": "string", "format": "date-time" }, "issue_url": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri", "description": "Direct URL to this update on the issue page (anchor link)" } } }, "IssueSummary": { "type": "object", "required": ["slug", "scheduled_at", "updated_at", "is_no_updates", "update_count"], "properties": { "slug": { "type": "string", "example": "2026-11-01-00-00" }, "scheduled_at": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "is_no_updates": { "type": "boolean", "description": "True if the issue explicitly contains no news events" }, "cover_url": { "type": "string", "format": "uri", "nullable": true }, "correction_note": { "type": "string", "nullable": true }, "update_count": { "type": "integer", "minimum": 0 } } }, "IssueDetail": { "allOf": [ { "$ref": "#/components/schemas/IssueSummary" }, { "type": "object", "required": ["updates"], "properties": { "updates": { "type": "array", "items": { "type": "object", "required": ["id", "title", "summary", "facts", "sources", "url"], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "summary": { "type": "string" }, "facts": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "url": { "type": "string", "format": "uri" } } } } } } ] }, "Error": { "type": "object", "required": ["error", "code"], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" } } } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_limit": { "value": { "error": "limit must be a positive integer", "code": "invalid_limit" } }, "missing_query": { "value": { "error": "q is required", "code": "missing_query" } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "value": { "error": "Issue not found", "code": "not_found" } } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "value": { "error": "Internal server error", "code": "internal_error" } } } } } } } }