{ "openapi": "3.0.3", "info": { "title": "Sylvia API", "version": "3.0.0", "description": "Sylvia API is a read-only Reddit data gateway serving structured JSON for posts, comments with full recursive threads, subreddits, users, search, and live comment streams. Authentication uses a single API key in the X-API-KEY header; no OAuth, no KYC.\n\n## Idempotency\nAll operations are HTTP GET and read-only: they do not mutate server state and are safe to retry. Repeated identical requests return identical data (modulo the live endpoints, which are inherently time-sensitive). No Idempotency-Key header is required.\n\n## Stable error envelope\nEvery response is wrapped in a stable envelope. On success: {\"success\": true, \"data\": {...}, \"request_id\": \"\"}. On failure: {\"success\": false, \"error\": \"\", \"request_id\": \"\"} with an appropriate 4xx/5xx status code. Error responses always reference the ErrorResponse schema.\n\n## Rate limiting\nRate limits are enforced per API key with a sliding window, signalled through response headers: X-RateLimit-Tier, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on 429. Tiers: Free (480 req/min), Strela (1,200), Svetka (2,400), Enterprise (3,600).\n\n## Live streams\nThe live endpoints (/comments/live and /r/{subreddit}/comments/live) return a paged poll of the newest comments. Pass the `after` cursor to advance. Each comment carries a stable, documented shape (see the onComment callback).\n\n## Agent access\nThe same surface is available as a Model Context Protocol (MCP) server at https://api.sylvia-api.com/mcp, and agent access semantics are declared in x-agentic-access. See https://sylvia-api.com/llms.txt.", "contact": { "name": "Sylvia API", "url": "https://sylvia-api.com", "email": "support@sylvia-api.com" }, "license": { "name": "Proprietary", "url": "https://sylvia-api.com/terms" }, "x-agentic-access": { "intent": "read-only", "authenticated": true, "idempotent": true, "rateLimits": { "headers": [ "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After" ], "statusCode": 429 }, "mcpServer": "https://api.sylvia-api.com/mcp", "llmsTxt": "https://sylvia-api.com/llms.txt" } }, "servers": [ { "url": "https://api.sylvia-api.com/v1", "description": "Production API server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/reddit/health": { "get": { "summary": "API health check", "description": "Returns service health status.", "operationId": "getHealth", "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "status": "ok", "uptime_seconds": 86400 }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Health" ], "parameters": [ { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ] } }, "/reddit/r/{subreddit}/about": { "get": { "summary": "Subreddit metadata", "description": "Returns subreddit info: members, description, NSFW flag, icon, creation date.", "operationId": "getSubredditAbout", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "description": "Subreddit name (without r/)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Subreddit metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubredditResponse" }, "example": { "success": true, "data": { "subreddit": { "name": "Python", "subscribers": 1400000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Subreddits" ] } }, "/reddit/r/{subreddit}/about/rules": { "get": { "summary": "Subreddit rules", "description": "Returns the list of rules for a subreddit.", "operationId": "getSubredditRules", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Subreddit rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "subreddit": { "name": "Python", "subscribers": 1400000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Subreddits" ] } }, "/reddit/r/{subreddit}/{sort}": { "get": { "summary": "Subreddit post listing", "description": "Returns posts from a subreddit by sort: hot, new, top, rising, or controversial.", "operationId": "getSubredditPosts", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sort", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hot", "new", "top", "rising", "controversial" ] } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Pagination token for previous page", "schema": { "type": "string" } }, { "name": "t", "in": "query", "description": "Time filter for top sort", "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year", "all" ] } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Paginated posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "subreddit": { "name": "Python", "subscribers": 1400000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Subreddits" ] } }, "/reddit/r/{subreddit}/comments/live": { "get": { "summary": "Subreddit live comment stream", "description": "Real-time comment stream for a subreddit. Billed at the Live Stream tier.", "operationId": "getSubredditLiveComments", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Live comment stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "comments": [ { "id": "1abc", "body": "Example comment", "subreddit": "all" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Live" ], "callbacks": { "onComment": { "{$request.body#/callbackUrl}": { "post": { "summary": "Live comment stream event (typed event surface)", "description": "When polling /comments/live or /r/{subreddit}/comments/live, each new comment is returned in the data.comments array with a stable shape: id, body, author, subreddit, created_utc, permalink, score.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" }, "example": { "id": "1abc", "body": "Example comment", "author": "user", "subreddit": "all", "created_utc": 1754132400, "score": 5 } } } }, "responses": { "200": { "description": "Acknowledged" } } } } } } } }, "/reddit/r/{subreddit}/sticky": { "get": { "summary": "Subreddit sticky posts", "description": "Returns stickied/pinned posts from a subreddit.", "operationId": "getSubredditSticky", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Sticky posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "subreddit": { "name": "Python", "subscribers": 1400000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Subreddits" ] } }, "/reddit/r/{subreddit}/wiki/pages": { "get": { "summary": "List subreddit wiki pages", "description": "Returns the list of wiki pages for a subreddit.", "operationId": "getSubredditWikiPages", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Wiki page list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "subreddit": { "name": "Python", "subscribers": 1400000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Subreddits" ] } }, "/reddit/r/{subreddit}/wiki/{page}": { "get": { "summary": "Get subreddit wiki page", "description": "Returns the content of a specific wiki page.", "operationId": "getSubredditWikiPage", "parameters": [ { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Wiki page content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "subreddit": { "name": "Python", "subscribers": 1400000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Subreddits" ] } }, "/reddit/u/{username}/about": { "get": { "summary": "User profile metadata", "description": "Returns user profile info: name, karma, account age, avatar, and more.", "operationId": "getUserAbout", "parameters": [ { "name": "username", "in": "path", "required": true, "description": "Username (without u/)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" }, "example": { "success": true, "data": { "user": { "name": "spez", "karma": 8000000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Users" ] } }, "/reddit/u/{username}/{where}": { "get": { "summary": "User content", "description": "Returns a user's submitted posts, comments, or combined overview.", "operationId": "getUserContent", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "where", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "submitted", "comments", "overview" ] } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Pagination token for previous page", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Paginated content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "user": { "name": "spez", "karma": 8000000 } }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Users" ] } }, "/reddit/submission": { "get": { "summary": "Fetch post by URL", "description": "Returns a single post given its full Reddit URL.", "operationId": "getSubmissionByUrl", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full Reddit post URL", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Post object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example post" } ], "after": "t3_1abc" }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Posts & Comments" ] } }, "/reddit/comment": { "get": { "summary": "Fetch comment by URL", "description": "Returns a single comment given its full Reddit permalink URL.", "operationId": "getCommentByUrl", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Full Reddit comment permalink URL", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Comment object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example post" } ], "after": "t3_1abc" }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Posts & Comments" ] } }, "/reddit/submission/{post_id}/full": { "get": { "summary": "Fully resolved thread", "description": "Returns the post listing plus all comments with recursive expansion of 'more' stubs (depth-limited).", "operationId": "getFullThread", "parameters": [ { "name": "post_id", "in": "path", "required": true, "description": "Reddit post ID (e.g. 'abc123' from t3_abc123)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Comment sort order", "schema": { "type": "string", "enum": [ "confidence", "top", "new", "controversial", "old", "qa" ], "default": "confidence" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Resolved thread [post_listing, comment_listing]", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example post" } ], "after": "t3_1abc" }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Posts & Comments" ] } }, "/reddit/search": { "get": { "summary": "Global Reddit search", "description": "Global keyword search across Reddit posts.", "operationId": "searchReddit", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "new", "relevance" ], "default": "new" } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "subreddit", "in": "query", "description": "Restrict to a subreddit", "schema": { "type": "string" } }, { "name": "include_over_18", "in": "query", "description": "Include NSFW results", "schema": { "type": "boolean" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example result" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Search" ] } }, "/reddit/comments/live": { "get": { "summary": "Global live comment firehose", "description": "Real-time comment stream from across all of Reddit. Billed at the Live Stream tier.", "operationId": "getGlobalLiveComments", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Live comment stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "comments": [ { "id": "1abc", "body": "Example comment", "subreddit": "all" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Live" ], "callbacks": { "onComment": { "{$request.body#/callbackUrl}": { "post": { "summary": "Live comment stream event (typed event surface)", "description": "When polling /comments/live or /r/{subreddit}/comments/live, each new comment is returned in the data.comments array with a stable shape: id, body, author, subreddit, created_utc, permalink, score.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" }, "example": { "id": "1abc", "body": "Example comment", "author": "user", "subreddit": "all", "created_utc": 1754132400, "score": 5 } } } }, "responses": { "200": { "description": "Acknowledged" } } } } } } } }, "/reddit/duplicates/{submission_id}": { "get": { "summary": "Crosspost duplicates", "description": "Returns crosspost duplicates of a submission.", "operationId": "getDuplicates", "parameters": [ { "name": "submission_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Duplicate submissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example post" } ], "after": "t3_1abc" }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Posts & Comments" ] } }, "/reddit/domain/{domain}/{sort}": { "get": { "summary": "Posts linking to a domain", "description": "Returns posts that link to a given domain, sorted by hot, new, top, rising, or controversial.", "operationId": "getDomainPosts", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name (e.g. github.com)", "schema": { "type": "string" } }, { "name": "sort", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "hot", "new", "top", "rising", "controversial" ] } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "t", "in": "query", "description": "Time filter for top sort", "schema": { "type": "string", "enum": [ "hour", "day", "week", "month", "year", "all" ] } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Paginated posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "url": "https://example.com" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Domains" ] } }, "/reddit/domain/{domain}": { "get": { "summary": "Posts linking to a domain", "description": "Returns posts that link to a given domain (default sort).", "operationId": "getDomainPostsDefault", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain name (e.g. github.com)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Paginated posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "url": "https://example.com" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Domains" ] } }, "/reddit/morechildren": { "get": { "summary": "Load more comments", "description": "Expands truncated 'more' comment stubs in a thread.", "operationId": "getMoreChildren", "parameters": [ { "name": "link_id", "in": "query", "required": true, "description": "Thread fullname (e.g. t3_abc123)", "schema": { "type": "string" } }, { "name": "children", "in": "query", "required": true, "description": "Comma-separated comment IDs to expand", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Comment sort order", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Resolved comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example post" } ], "after": "t3_1abc" }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Posts & Comments" ] } }, "/reddit/by_id": { "get": { "summary": "Fetch by fullname IDs", "description": "Bulk fetch posts, comments, or subreddits by their fullnames.", "operationId": "getByIds", "parameters": [ { "name": "names", "in": "query", "required": true, "description": "Comma-separated fullnames (e.g. t3_abc,t3_def), max 100", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Requested objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "posts": [ { "id": "1abc", "title": "Example post" } ], "after": "t3_1abc" }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Posts & Comments" ] } }, "/reddit/subreddits/{category}": { "get": { "summary": "Browse subreddits", "description": "Returns subreddit listings by category: popular, default, new, or premium.", "operationId": "browseSubreddits", "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "popular", "default", "new", "premium" ] } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "after", "in": "query", "description": "Pagination token from previous response", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Subreddit listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "subreddits": [ { "name": "Python" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Discovery" ] } }, "/reddit/subreddits/search": { "get": { "summary": "Search subreddits", "description": "Search subreddits by name or description.", "operationId": "searchSubreddits", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query for subreddit name/description", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Matching subreddits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "subreddits": [ { "name": "Python" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Discovery" ] } }, "/reddit/subreddit_autocomplete": { "get": { "summary": "Autocomplete subreddit names", "description": "Autocompletes subreddit names by partial query.", "operationId": "autocompleteSubreddit", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Partial subreddit name prefix", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Items per page (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "format", "in": "query", "description": "Response format. 'reddit' (default) is raw JSON. 'markdown' is available on all tiers; 'minimal' and 'csv' require Strela; 'ndjson' requires Svetka; 'custom(name)' applies a saved template.", "schema": { "type": "string", "enum": [ "reddit", "minimal", "ndjson", "csv", "markdown" ], "default": "reddit" } } ], "responses": { "200": { "description": "Subreddit suggestions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": { "subreddits": [ { "name": "Python" } ] }, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Discovery" ] } }, "/auth/me": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "Get account profile", "operationId": "getAccountProfile", "security": [ { "AccountTokenAuth": [] } ], "responses": { "200": { "description": "Account profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfo" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Account" ] } }, "/auth/recent-requests": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "Recent request history", "operationId": "getRecentRequests", "security": [ { "AccountTokenAuth": [] } ], "parameters": [ { "name": "max", "in": "query", "description": "Max entries (default 100)", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Recent requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Account" ] } }, "/auth/usage-history": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "Per-day usage analytics", "operationId": "getUsageHistory", "security": [ { "AccountTokenAuth": [] } ], "parameters": [ { "name": "days", "in": "query", "description": "Days of history (default 14)", "schema": { "type": "integer", "default": 14 } } ], "responses": { "200": { "description": "Usage history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Account" ] } }, "/auth/formats": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "List available response formats", "operationId": "listFormats", "security": [ { "AccountTokenAuth": [] } ], "responses": { "200": { "description": "Available formats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormatsResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Account" ] } }, "/auth/default-format": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "post": { "summary": "Set default response format", "operationId": "setDefaultFormat", "security": [ { "AccountTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated default format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Account" ] } }, "/keys": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "List API keys", "operationId": "listApiKeys", "security": [ { "AccountTokenAuth": [] } ], "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Keys" ] }, "post": { "summary": "Create API key", "operationId": "createApiKey", "security": [ { "AccountTokenAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "expiry": { "type": "string" }, "budget": { "type": "number" } } } } } }, "responses": { "200": { "description": "Created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Keys" ] } }, "/keys/{key_id}": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "delete": { "summary": "Revoke API key", "operationId": "revokeApiKey", "security": [ { "AccountTokenAuth": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Keys" ] } }, "/templates": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "List custom templates", "operationId": "listTemplates", "security": [ { "AccountTokenAuth": [] } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Templates" ] }, "post": { "summary": "Create custom template", "operationId": "createTemplate", "security": [ { "AccountTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "schema" ], "properties": { "name": { "type": "string" }, "schema": { "type": "object" } } } } } }, "responses": { "200": { "description": "Created template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Templates" ] } }, "/templates/{name}": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "delete": { "summary": "Delete custom template", "operationId": "deleteTemplate", "security": [ { "AccountTokenAuth": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Templates" ] } }, "/createPayment": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "post": { "summary": "Create crypto deposit payment", "operationId": "createPayment", "security": [ { "AccountTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number" } } } } } }, "responses": { "200": { "description": "Payment link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Billing" ] } }, "/paymentStatus/{id}": { "servers": [ { "url": "https://api.sylvia-api.com" } ], "get": { "summary": "Get payment status", "operationId": "getPaymentStatus", "security": [ { "AccountTokenAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true, "data": {}, "request_id": "00000000-0000-0000-0000-000000000000" } } }, "headers": { "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "tags": [ "Billing" ] } } }, "components": { "schemas": { "Envelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "request_id": { "type": "string" } } }, "Post": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "selftext": { "type": "string" }, "author": { "type": "string" }, "subreddit": { "type": "string" }, "score": { "type": "integer" }, "upvote_ratio": { "type": "number" }, "num_comments": { "type": "integer" }, "created_utc": { "type": "integer", "format": "int64" }, "permalink": { "type": "string" }, "url": { "type": "string" }, "is_self": { "type": "boolean" }, "over_18": { "type": "boolean" }, "stickied": { "type": "boolean" } } }, "Comment": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author": { "type": "string" }, "subreddit": { "type": "string" }, "score": { "type": "integer" }, "created_utc": { "type": "integer", "format": "int64" }, "permalink": { "type": "string" }, "parent_id": { "type": "string" }, "link_id": { "type": "string" }, "submission_id": { "type": "string" }, "depth": { "type": "integer" } } }, "Subreddit": { "type": "object", "properties": { "name": { "type": "string" }, "members": { "type": "integer" }, "description": { "type": "string" }, "is_private": { "type": "boolean" }, "over18": { "type": "boolean" }, "icon_img": { "type": "string", "nullable": true }, "created_utc": { "type": "integer", "format": "int64" } } }, "User": { "type": "object", "properties": { "name": { "type": "string" }, "created_utc": { "type": "integer", "format": "int64" }, "link_karma": { "type": "integer" }, "comment_karma": { "type": "integer" }, "icon_img": { "type": "string", "nullable": true } } }, "ListingData": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "after": { "type": "string", "nullable": true } } }, "ListingResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListingData" } } } ] }, "SubredditResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Subreddit" } } } ] }, "UserResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } ] }, "PostResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Post" } } } ] }, "CommentResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Comment" } } } ] }, "ThreadResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "array", "description": "Reddit thread format [post_listing, comment_listing]", "items": { "type": "object" } } } } ] }, "GenericResponse": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "request_id": { "type": "string" } } }, "UserInfo": { "type": "object", "properties": { "token": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "boolean" }, "balance": { "type": "number" }, "tier": { "type": "string", "enum": [ "free", "strela", "svetka", "enterprise" ] }, "tierExpiry": { "type": "string", "nullable": true }, "status": { "type": "string" }, "defaultFormat": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "prefix": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "expiry": { "type": "string", "nullable": true }, "budget": { "type": "number", "nullable": true } } }, "ApiKeyList": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "FormatInfo": { "type": "object", "properties": { "name": { "type": "string" }, "minTier": { "type": "string" }, "available": { "type": "boolean" } } }, "FormatsResponse": { "type": "object", "properties": { "tier": { "type": "string" }, "defaultFormat": { "type": "string", "nullable": true }, "formats": { "type": "array", "items": { "$ref": "#/components/schemas/FormatInfo" } } } }, "CreateKeyResponse": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" } } }, "Template": { "type": "object", "properties": { "name": { "type": "string" }, "schema": { "type": "object" } } } }, "responses": { "BadRequest": { "description": "Bad request — invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden — insufficient access or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication. Get yours at https://sylvia-api.com" }, "AccountTokenAuth": { "type": "apiKey", "in": "header", "name": "x-sylvia-auth", "description": "Account token (SV_...) for account management endpoints. Sign in at https://sylvia-api.com to get yours." } }, "headers": { "X-RateLimit-Tier": { "description": "Rate limit tier: free | strela | svetka | enterprise.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests per second for the tier.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch milliseconds when the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until retry is allowed, present on 429.", "schema": { "type": "integer" } } } } }