{ "openapi": "3.1.0", "info": { "title": "Sukidata API", "version": "1.0.0", "description": "Retrieve web data and create or edit images through product-specific APIs." }, "servers": [ { "url": "https://api.sukidata.com" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Search", "description": "Create and retrieve Google SERP searches." }, { "name": "Twitter", "description": "Retrieve public posts from a Twitter user timeline." }, { "name": "Search configuration", "description": "Discover supported targeting values." }, { "name": "Activity", "description": "Review Web Data requests in your Workspace." }, { "name": "Result files", "description": "Retrieve generated JSON and HTML result files." }, { "name": "API schema", "description": "Access the machine-readable API contract." }, { "name": "Images", "description": "Generate images from prompts or edit reference images." }, { "name": "Model catalog", "description": "Discover available AI models." }, { "name": "Image tasks", "description": "Track image tasks and retrieve results." } ], "x-tagGroups": [ { "name": "Common", "tags": [ "API schema" ] }, { "name": "Web Data", "tags": [ "Search", "Twitter", "Search configuration", "Activity", "Result files" ] }, { "name": "AI", "tags": [ "Model catalog", "Images", "Image tasks" ] } ], "paths": { "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "Get the OpenAPI document", "tags": [ "API schema" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 JSON document.", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/activity": { "get": { "operationId": "listSearchActivity", "summary": "List search activity", "tags": [ "Activity" ], "parameters": [ { "$ref": "#/components/parameters/ListLimit" }, { "$ref": "#/components/parameters/ListCursor" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 512 }, "description": "Search by search ID, request ID, query, Twitter username or user ID, or location." }, { "name": "endpoint", "in": "query", "schema": { "type": "string", "enum": [ "serp", "/v1/serp", "twitter", "/v1/twitter" ] }, "description": "Filter by product name or its `/v1/...` path." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "success", "running", "failed", "cache" ] }, "description": "Filter by status. `cache` selects cached responses." }, { "name": "api_key_id", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,128}$" }, "description": "Filter by API key ID." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower bound for `created_at`." } ], "responses": { "200": { "description": "Recent requests in your Workspace.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/activity/{search_id}": { "get": { "operationId": "getSearchActivity", "summary": "Get search activity", "tags": [ "Activity" ], "parameters": [ { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Request details in your Workspace.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/serp/locations": { "get": { "operationId": "searchGoogleLocations", "summary": "Search supported locations", "tags": [ "Search configuration" ], "security": [], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 4096 }, "description": "Optional location search text. Omit it to list supported Google locations." }, { "name": "limit", "in": "query", "description": "Maximum number of locations to return. Defaults to 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 } } ], "responses": { "200": { "description": "Matching supported Google locations.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleLocations" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServiceError" } } } }, "/v1/serp/google-support": { "get": { "operationId": "listGoogleSearchParameters", "summary": "List supported Google parameters", "tags": [ "Search configuration" ], "security": [], "responses": { "200": { "description": "Supported Google domains, country codes, interface languages, and restrict tokens.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleSupport" } } } }, "500": { "$ref": "#/components/responses/ServiceError" } } } }, "/v1/serp": { "post": { "operationId": "createSerpSearch", "summary": "Create a SERP search", "tags": [ "Search" ], "parameters": null, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPRequest" }, "example": { "q": "coffee shops in seattle", "location": "Seattle, Washington, United States", "hl": "en" } } } }, "responses": { "200": { "description": "Search envelope, completed result, or failed result.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "callbacks": { "serpWebhook": { "{$request.body#/webhook/url}": { "post": { "summary": "Optional SERP webhook delivery.", "description": "Sent when the caller provides `webhook.url` and subscribes to a matching event. Failed deliveries may be retried.", "parameters": [ { "name": "X-Sukidata-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "serp.search.queued", "serp.search.processing", "serp.search.completed", "serp.search.failed" ] } }, { "name": "X-Sukidata-Delivery", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "HMAC signature in `v1=` format when a webhook secret is available for the authenticated API key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "The webhook endpoint accepted the delivery." } } } } } } } }, "/v1/serp/{search_id}": { "get": { "operationId": "getSerpSearch", "summary": "Get a SERP search", "tags": [ "Search" ], "parameters": [ { "name": "search_id", "in": "path", "required": true, "description": "Search ID returned by POST /v1/serp. Malformed IDs return 400; IDs unavailable to the authenticated workspace return 404.", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Search envelope, completed result, or failed result.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SERPEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/twitter": { "post": { "operationId": "createTwitterSearch", "summary": "Get a Twitter user timeline", "description": "Retrieves one page of public posts for a user. Pass `next_cursor` as `cursor` in a later request to continue. Successful requests use one credit per 10 returned posts, rounded up, with a one-credit minimum.", "tags": [ "Twitter" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterRequest" }, "example": { "username": "sukidata", "max_results": 20 } } } }, "responses": { "200": { "description": "Search envelope, completed timeline, or failed result.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "callbacks": { "twitterWebhook": { "{$request.body#/webhook/url}": { "post": { "summary": "Optional Twitter webhook delivery.", "description": "Sent when the caller provides `webhook.url` and subscribes to a matching event. Failed deliveries may be retried.", "parameters": [ { "name": "X-Sukidata-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "twitter.search.queued", "twitter.search.processing", "twitter.search.completed", "twitter.search.failed" ] } }, { "name": "X-Sukidata-Delivery", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Sukidata-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "HMAC signature in `v1=` format when a webhook secret is available for the authenticated API key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterWebhookPayload" } } } }, "responses": { "2XX": { "description": "The webhook endpoint accepted the delivery." } } } } } } } }, "/v1/twitter/{search_id}": { "get": { "operationId": "getTwitterSearch", "summary": "Get a Twitter timeline request", "tags": [ "Twitter" ], "parameters": [ { "name": "search_id", "in": "path", "required": true, "description": "Search ID returned by POST /v1/twitter. Malformed IDs return 400; IDs unavailable to the authenticated workspace return 404.", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "Search envelope, completed timeline, or failed result.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Cache-Hit": { "$ref": "#/components/headers/SukidataCacheHit" }, "X-Sukidata-Credits-Used": { "$ref": "#/components/headers/SukidataCreditsUsed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServiceError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/models": { "get": { "operationId": "listModels", "summary": "List available AI models", "description": "List the models available to your API key.", "tags": [ "Model catalog" ], "responses": { "200": { "description": "Available models in the OpenAI-compatible list format.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AIModel" } } } } } } }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/generations": { "post": { "operationId": "generateImages", "summary": "Generate images", "description": "Generate images from a prompt, with optional reference images. Returns Base64 data by default; set response_format to url for image URLs.", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageGeneration" }, "responses": { "200": { "$ref": "#/components/responses/ImageResult" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/generations/async": { "post": { "operationId": "generateImagesAsync", "summary": "Submit image generation", "description": "Submit an image generation task. Poll the URL in the Location header for progress and results.", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageGeneration" }, "responses": { "202": { "$ref": "#/components/responses/ImageAccepted" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/edits": { "post": { "operationId": "editImages", "summary": "Edit images", "description": "Edit images using a prompt and reference images. Upload files with multipart/form-data or use image URLs in JSON. An optional mask selects the area to edit.", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageEdit" }, "responses": { "200": { "$ref": "#/components/responses/ImageResult" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/edits/async": { "post": { "operationId": "editImagesAsync", "summary": "Submit an image edit", "description": "Submit an image editing task. Uses the same parameters and input limits as synchronous editing.", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdempotencyKey" } ], "requestBody": { "$ref": "#/components/requestBodies/ImageEdit" }, "responses": { "202": { "$ref": "#/components/responses/ImageAccepted" }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/tasks": { "get": { "operationId": "listImageTasks", "summary": "List image tasks", "description": "List your Workspace's image tasks, including status, charges and image links.", "tags": [ "Image tasks" ], "parameters": [ { "$ref": "#/components/parameters/ListLimit" }, { "$ref": "#/components/parameters/ListCursor" }, { "name": "model", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ImageTaskStatus" } }, { "name": "search", "in": "query", "description": "Search prompt text or task ID.", "schema": { "type": "string", "maxLength": 256 } }, { "name": "operation", "in": "query", "schema": { "enum": [ "images.generations", "images.edits" ] } }, { "name": "api_key_id", "in": "query", "description": "Filter by the key ID that submitted the request, including a deleted key. Omit for all sources, including Playground.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "created_from", "in": "query", "description": "Inclusive creation time, as an RFC 3339 timestamp with timezone.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_to", "in": "query", "description": "Exclusive creation time, as an RFC 3339 timestamp with timezone. Must be later than created_from.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Most recent tasks first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTaskSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/v1/images/tasks/{task_id}": { "get": { "operationId": "getImageTask", "summary": "Get an image task", "description": "Get a task's prompt, parameters, status, images and charge. Requires an API key from the same Workspace.", "tags": [ "Image tasks" ], "parameters": [ { "$ref": "#/components/parameters/ImageTaskID" } ], "responses": { "200": { "description": "Image task detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTask" } } } }, "default": { "$ref": "#/components/responses/ImageError" } } } }, "/searches/{file_token}/{search_id}.{format}": { "servers": [ { "url": "https://files.sukidata.com" } ], "get": { "operationId": "getSearchResultFile", "summary": "Get a result file", "tags": [ "Result files" ], "description": "Returns a result file referenced by `search_metadata.json_endpoint` or `search_metadata.raw_html_file`. File URLs do not require API authentication and remain available for one month, so keep them private. HTML is available only for products that capture a source page.", "security": [], "parameters": [ { "name": "file_token", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "json", "html" ] } } ], "responses": { "200": { "description": "JSON search envelope for `.json`, or an HTML snapshot for `.html`.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Caching policy for the result file." } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SERPEnvelope" }, { "$ref": "#/components/schemas/TwitterEnvelope" } ] } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "parameters": { "ImageIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Reuse this key, parameters and files when retrying a task. The key is scoped to Workspace and operation, shared by synchronous and asynchronous submissions. Changed input returns 409. A new key creates a new task. Interrupted uploads must be retried within ten minutes of task creation; after that, the task fails without a charge and a new key is required.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" } }, "ImageTaskID": { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "ListLimit": { "name": "limit", "in": "query", "description": "Maximum number of records to return. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "ListCursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned by the previous list response." } }, "headers": { "ImageTaskID": { "description": "Task ID, returned once a task is created. Use it to check the result after a timeout.", "schema": { "type": "string" } }, "RequestID": { "description": "Request identifier to include when contacting support.", "schema": { "$ref": "#/components/schemas/RequestID" } }, "SukidataCacheHit": { "description": "Whether this request qualified for a zero-credit cached response.", "schema": { "type": "boolean" } }, "SukidataCreditsUsed": { "description": "Credits charged when the search reaches `Success` or `Error`. Omitted while in progress; cached responses use `0`.", "schema": { "type": "integer", "format": "int64" } } }, "responses": { "ImageResult": { "description": "Generated images.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Task-ID": { "$ref": "#/components/headers/ImageTaskID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResult" } } } }, "ImageAccepted": { "description": "Task ID and current status. Reusing an idempotency key returns the same task.", "headers": { "X-Sukidata-Task-ID": { "$ref": "#/components/headers/ImageTaskID" }, "Location": { "description": "Authenticated URL for task detail and progress.", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "status" ], "properties": { "id": { "type": "string" }, "object": { "const": "image.task" }, "status": { "$ref": "#/components/schemas/ImageTaskStatus" } } } } } }, "ImageError": { "description": "HTTP errors: 400 invalid input or model; 401 missing or invalid API key; 402 insufficient AI balance; 403 access denied; 404 task not found; 409 idempotency conflict; 410 expired upload or image link; 413 request too large; 502 generation failed; 503 service unavailable or result pending. If X-Sukidata-Task-ID is present, query the task before retrying.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "X-Sukidata-Task-ID": { "$ref": "#/components/headers/ImageTaskID" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ImageErrorDetail" } } } } } }, "BadRequest": { "description": "Invalid request parameters.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "API key missing, invalid, inactive, revoked, or expired.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PaymentRequired": { "description": "Credit is insufficient; search was not created.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Access denied for this API key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "Search not found for this workspace context.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "PayloadTooLarge": { "description": "Request body is too large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UnsupportedMediaType": { "description": "Request content type must be application/json.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServiceError": { "description": "Unexpected service error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServiceUnavailable": { "description": "Service temporarily unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBodies": { "ImageGeneration": { "required": true, "description": "JSON or multipart request, up to 48 MiB. Optional reference images must be PNG, JPEG or WebP. The selected model determines the maximum number of reference images.", "content": { "application/json": { "example": { "model": "gpt-image-2.5", "prompt": "A blue ceramic cup on a plain white background" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageReferenceFields" } ], "unevaluatedProperties": false } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageMultipartFields" } ], "unevaluatedProperties": false } } } }, "ImageEdit": { "required": true, "description": "JSON or multipart request with at least one reference image, up to 48 MiB per request. Inputs must be PNG, JPEG or WebP. The selected model determines the maximum number of reference images.", "content": { "application/json": { "example": { "model": "gpt-image-2.5", "prompt": "Change the cup to green, keeping the composition", "images": [ { "image_url": "https://example.com/input.png" } ] }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageReferenceFields" }, { "type": "object", "anyOf": [ { "required": [ "image" ] }, { "required": [ "images" ] } ], "properties": { "mask": { "$ref": "#/components/schemas/ImageMask" } } } ], "unevaluatedProperties": false } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ImageRequestFields" }, { "$ref": "#/components/schemas/ImageMultipartFields" }, { "type": "object", "anyOf": [ { "required": [ "image" ] }, { "required": [ "image[]" ] } ], "properties": { "mask": { "type": "string", "format": "binary", "description": "PNG mask with an alpha channel, matching the first reference image's dimensions. Transparent areas mark where to edit. The mask does not count toward the reference-image limit." } } } ], "unevaluatedProperties": false } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key created in the Sukidata console." } }, "schemas": { "ImageReferenceFields": { "type": "object", "description": "Choose one field, image or images. Either accepts a single reference or an array.", "not": { "required": [ "image", "images" ] }, "properties": { "image": { "$ref": "#/components/schemas/ImageReferences" }, "images": { "$ref": "#/components/schemas/ImageReferences" } } }, "ImageReferences": { "oneOf": [ { "$ref": "#/components/schemas/ImageReference" }, { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/ImageReference" } } ] }, "ImageReference": { "oneOf": [ { "type": "string", "minLength": 1, "description": "Public HTTPS image URL or a PNG, JPEG or WebP Base64 data URL." }, { "type": "object", "additionalProperties": false, "properties": { "image_url": { "type": "string", "minLength": 1, "description": "Public HTTPS image URL or a PNG, JPEG or WebP Base64 data URL." }, "b64_json": { "type": "string", "minLength": 1, "contentEncoding": "base64", "description": "PNG, JPEG or WebP reference image encoded as Base64." } }, "oneOf": [ { "required": [ "image_url" ] }, { "required": [ "b64_json" ] } ] } ] }, "ImageMask": { "allOf": [ { "$ref": "#/components/schemas/ImageReference" } ], "description": "PNG mask with an alpha channel, matching the first reference image's dimensions. Transparent areas mark where to edit. The mask does not count toward the reference-image limit." }, "ImageMultipartFields": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "PNG, JPEG or WebP file. For multiple files, repeat the image[] field." }, "image[]": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "format": "binary" } } } }, "AIModel": { "type": "object", "required": [ "id", "object", "created", "owned_by" ], "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "created": { "type": "integer", "format": "int64", "description": "Unix timestamp in seconds." }, "owned_by": { "const": "sukidata" } } }, "ImageRequestFields": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 128, "description": "An available model ID from /v1/models, such as gpt-image-2.5 or gpt-image-2." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 }, "size": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^(auto|[1-9][0-9]{0,3}x[1-9][0-9]{0,3})$", "description": "Requested size as auto or WIDTHxHEIGHT. Width and height must be positive integers up to 3840, with an aspect ratio between 1:3 and 3:1 and 655360 to 8294400 total pixels. Omission uses the model default." }, "quality": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Quality supported by the selected model. Omission uses the model default." }, "n": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of images to generate, subject to the selected model's limit. gpt-image-2.5 and gpt-image-2 support 1 to 4 images per request; the default is 1." }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ], "default": "png" }, "background": { "type": "string", "enum": [ "auto", "opaque", "transparent" ], "description": "Transparent output requires PNG or WebP." }, "moderation": { "type": "string", "enum": [ "auto", "low" ] }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Output compression for JPEG and WebP. Accepted but not applied to PNG." }, "response_format": { "type": "string", "enum": [ "b64_json", "url" ], "default": "b64_json", "description": "Delivery format for synchronous responses. Asynchronous tasks expose public image URLs in task detail." }, "stream": { "type": "boolean", "const": false, "description": "Set to false or omit. For background generation, use the asynchronous endpoints." }, "user": { "type": "string", "maxLength": 256, "description": "Your end-user identifier, saved with the task." } } }, "ImageResult": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ImageResultMetadata" } ], "required": [ "created", "data" ], "properties": { "created": { "type": "integer", "format": "int64", "description": "Task creation time, as a Unix timestamp in seconds." }, "data": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "oneOf": [ { "required": [ "b64_json" ] }, { "required": [ "url" ] } ], "properties": { "b64_json": { "type": "string", "contentEncoding": "base64" }, "url": { "type": "string", "format": "uri", "description": "Image URL, available for 31 days from publication. Anyone with the URL can view the image." } } } } } }, "ImageResultMetadata": { "type": "object", "description": "Output metadata, when available. Mixed-size batches omit the top-level size; individual dimensions are available in the task's images array.", "properties": { "background": { "enum": [ "opaque", "transparent" ] }, "output_format": { "enum": [ "png", "jpeg", "webp" ] }, "size": { "type": "string" }, "quality": { "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "usage": { "$ref": "#/components/schemas/ImageTokenUsage" } } }, "ImageTokenUsage": { "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens" ], "description": "Token usage, when available. Per-image pricing does not add token charges.", "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 }, "total_tokens": { "type": "integer", "minimum": 0 }, "input_tokens_details": { "$ref": "#/components/schemas/ImageTokenDetails" }, "output_tokens_details": { "$ref": "#/components/schemas/ImageTokenDetails" } } }, "ImageTokenDetails": { "type": "object", "properties": { "text_tokens": { "type": "integer", "minimum": 0 }, "image_tokens": { "type": "integer", "minimum": 0 }, "cached_tokens": { "type": "integer", "minimum": 0 } } }, "ImageTaskStatus": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "unknown" ], "description": "Task progress. An unknown result is not a confirmed failure; query the same task again." }, "ImageContentStatus": { "type": "string", "enum": [ "pending", "ready", "unavailable" ], "description": "Availability of the generated image files." }, "ImageTaskSummary": { "type": "object", "required": [ "id", "model", "operation", "prompt_preview", "status", "content_status", "billing_status", "billing", "api_key_id", "image_count", "images", "created_at", "completed_at", "url" ], "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "operation": { "enum": [ "images.generations", "images.edits" ] }, "prompt_preview": { "type": "string" }, "status": { "$ref": "#/components/schemas/ImageTaskStatus" }, "content_status": { "$ref": "#/components/schemas/ImageContentStatus" }, "billing_status": { "type": "string", "description": "Billing status. A completed task may still have a pending charge." }, "billing": { "$ref": "#/components/schemas/ImageBilling" }, "api_key_id": { "type": [ "string", "null" ], "description": "API key ID used to submit the task. Null if unavailable." }, "image_count": { "type": "integer", "minimum": 0, "description": "Number of generated images available in this response." }, "images": { "type": "array", "description": "Image URLs and expiry times. Empty until the images are ready.", "items": { "type": "object", "required": [ "index", "url", "width", "height" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" }, "url_expires_at": { "type": "string", "format": "date-time", "description": "Public link expiry time. Save the image before this time; expired images cannot be retrieved through the API." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Preview image URL, when available. Expires with the original. Use url for full-resolution images." }, "width": { "type": "integer", "minimum": 1, "description": "Original image width in pixels." }, "height": { "type": "integer", "minimum": 1, "description": "Original image height in pixels." } } } }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "Task detail URL. Requires API authentication." } } }, "ImageFile": { "type": "object", "required": [ "index", "url", "width", "height", "format" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" }, "url_expires_at": { "type": "string", "format": "date-time", "description": "Public link expiry time. Save the image before this time; expired images cannot be retrieved through the API." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Preview image URL, when available. Expires with the original. Use url for full-resolution images." }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "format": { "enum": [ "png", "jpeg", "webp" ] } } }, "ImageTask": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ImageResultMetadata" } ], "required": [ "id", "object", "model", "operation", "status", "content_status", "created_at", "completed_at", "prompt", "parameters", "images", "billing" ], "properties": { "id": { "type": "string" }, "object": { "const": "image.task" }, "model": { "type": "string" }, "operation": { "enum": [ "images.generations", "images.edits" ] }, "status": { "$ref": "#/components/schemas/ImageTaskStatus" }, "content_status": { "$ref": "#/components/schemas/ImageContentStatus" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "prompt": { "type": "string" }, "parameters": { "type": "object", "description": "Parameters submitted with this task." }, "effective_parameters": { "type": "object", "description": "Size, quality and image count used for this task, including model defaults. Other settings are in parameters.", "properties": { "size": { "type": "string" }, "quality": { "type": "string" }, "n": { "type": "integer" } } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageFile" } }, "billing": { "$ref": "#/components/schemas/ImageBilling" }, "error": { "$ref": "#/components/schemas/ImageErrorDetail" } } }, "ImageBilling": { "type": "object", "required": [ "balance_type", "currency", "status", "reserved_amount", "charged_amount" ], "properties": { "balance_type": { "const": "ai" }, "currency": { "const": "USD" }, "status": { "type": "string", "enum": [ "pending", "reserved", "review", "settled", "released", "rejected", "unavailable" ], "description": "Billing status. Amounts are null when the status is unavailable." }, "reserved_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "Funds currently reserved for this task, in USD. Null if pending or unavailable." }, "charged_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "Charge in USD, after any corrections. Null if pending or unavailable." }, "original_charged_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "Original charge in USD, before corrections. Null if pending or unavailable." }, "credited_amount": { "type": [ "string", "null" ], "pattern": "^[0-9]+\\.[0-9]{9}$", "description": "Amount returned to AI balance for this task, in USD. Null if pending or unavailable." } } }, "ImageErrorDetail": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string" } } }, "RequestID": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } } }, "ActivityList": { "type": "object", "required": [ "data", "has_more" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "cursor": { "type": "string", "description": "Cursor to pass to the next request. Omitted when `has_more=false`." }, "has_more": { "type": "boolean" } } }, "ActivityItem": { "type": "object", "required": [ "search_id", "product", "engine", "status", "cache_hit", "created_at" ], "additionalProperties": false, "properties": { "search_id": { "type": "string" }, "request_id": { "type": "string", "description": "Request ID to include when contacting support." }, "api_key_id": { "type": "string", "description": "API key id used by the original search request." }, "product": { "type": "string" }, "engine": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Success", "Error" ] }, "cache_hit": { "type": "boolean", "description": "Whether this search qualified for a zero-credit cached response." }, "credits_used": { "type": "integer", "format": "int64", "description": "Credits consumed by this search. Omitted until the search reaches `Success` or `Error`." }, "q": { "type": "string", "description": "Search query when available." }, "search_parameters": { "type": "object", "additionalProperties": true, "description": "Search parameters that can be reused in another request." }, "location_requested": { "type": "string" }, "location_used": { "type": "string" }, "google_url": { "type": "string", "format": "uri" }, "error_code": { "type": "string", "description": "Error code returned for an unsuccessful search.", "const": "search_failed" }, "error_message": { "type": "string", "description": "Error message returned for an unsuccessful search.", "const": "Search request failed" }, "json_endpoint": { "type": "string", "format": "uri", "description": "JSON result file, available once the search reaches `Success` or `Error`." }, "raw_html_file": { "type": "string", "format": "uri", "description": "HTML result file, included after the search finishes if HTML is available." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "GoogleLocations": { "type": "object", "required": [ "locations" ], "additionalProperties": false, "properties": { "locations": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/GoogleLocation" } } } }, "GoogleSupport": { "type": "object", "required": [ "domains", "countries", "languages", "cr_countries", "lr_languages" ], "additionalProperties": false, "properties": { "domains": { "$ref": "#/components/schemas/StringList" }, "countries": { "$ref": "#/components/schemas/StringList" }, "languages": { "$ref": "#/components/schemas/StringList" }, "cr_countries": { "$ref": "#/components/schemas/StringList" }, "lr_languages": { "$ref": "#/components/schemas/StringList" } } }, "StringList": { "type": "array", "items": { "type": "string" } }, "GoogleLocation": { "type": "object", "required": [ "id", "google_id", "name", "canonical_name", "country_code", "target_type", "reach" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "google_id": { "type": "integer", "format": "int64" }, "google_parent_id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "canonical_name": { "type": "string" }, "country_code": { "type": "string" }, "target_type": { "type": "string" }, "reach": { "type": "integer", "format": "int64" }, "gps": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } } } }, "SERPRequest": { "type": "object", "description": "Parameters for a Google SERP request. String fields are trimmed and limited to 4096 UTF-8 bytes unless a narrower field-specific limit is documented.", "required": [ "q" ], "additionalProperties": false, "properties": { "engine": { "type": "string", "enum": [ "google" ], "maxLength": 4096, "default": "google" }, "q": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "\\S", "description": "Google search query. Advanced operators such as site:, inurl:, and intitle: are allowed." }, "as_dt": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google search parameter used with as_sitesearch to include or exclude a site." }, "as_epq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google exact phrase query." }, "as_eq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google excluded query terms." }, "as_lq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google linked-page query URL." }, "as_nlo": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google numeric range lower bound." }, "as_nhi": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google numeric range upper bound." }, "as_oq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google optional terms query." }, "as_q": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google additional query terms." }, "as_qdr": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google quick date range, such as d10, w2, m1, or y." }, "as_rq": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google related-page query URL." }, "as_sitesearch": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Advanced Google site restriction or exclusion target." }, "location": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Supported Google search location name or ID returned by GET /v1/serp/locations. Mutually exclusive with uule." }, "google_domain": { "type": "string", "default": "google.com", "maxLength": 4096, "pattern": "^[Gg][Oo][Oo][Gg][Ll][Ee](?:\\.[Cc][Oo][Mm]|\\.[A-Za-z]{2}|\\.(?:[Cc][Oo][Mm]|[Cc][Oo])\\.[A-Za-z]{2})$", "description": "Google search domain without scheme or path, such as google.com, google.de, google.co.jp, or google.com.br. Input is case-insensitive, normalized to lowercase, and validated against the supported Google domain list." }, "gl": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$", "default": "us", "description": "Two-letter Google country code. Input is case-insensitive, normalized to lowercase, and validated against the supported Google country list." }, "hl": { "type": "string", "minLength": 2, "maxLength": 32, "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "default": "en", "description": "Google interface language code such as en, ja, pt-br, or zh-cn. Input is normalized to lowercase and validated against the supported Google interface language list." }, "uule": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google encoded location. Mutually exclusive with location." }, "lat": { "oneOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "string", "pattern": "^-?(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$" }, { "type": "null" } ], "description": "Latitude for GPS-based Google localization. Must be used with lon and is mutually exclusive with location and uule." }, "lon": { "oneOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "string", "pattern": "^-?(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$" }, { "type": "null" } ], "description": "Longitude for GPS-based Google localization. Must be used with lat and is mutually exclusive with location and uule." }, "radius": { "oneOf": [ { "type": "number", "minimum": 1 }, { "type": "string", "pattern": "^(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$" }, { "type": "null" } ], "description": "Search radius for location or GPS-based localization. Maximum is 199 for desktop and 1000 for tablet or mobile. Mutually exclusive with uule." }, "ludocid": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google CID for a place result." }, "lsig": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google lsig value used by some local and knowledge graph views." }, "kgmid": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google Knowledge Graph entity ID." }, "si": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google encrypted/cached search parameter token." }, "ibp": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google layout or expansion parameter." }, "uds": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google filter token returned by SERP filter links." }, "cr": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google country restrict filter, as one or more countryXX tokens separated by `|`, such as `countryUS|countryJP`." }, "lr": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Google language restrict filter, as one or more lang_xx tokens separated by `|`, such as `lang_en|lang_zh-CN`." }, "tbs": { "type": [ "string", "null" ], "maxLength": 4096 }, "tbm": { "type": [ "string", "null" ], "enum": [ "isch", "lcl", "vid", "nws", "shop", "pts", null ], "maxLength": 4096, "description": "Supported Google search type. Omit the parameter for regular Google Search." }, "safe": { "type": "string", "enum": [ "off", "active" ], "maxLength": 4096, "default": "off" }, "nfpr": { "type": "boolean", "default": false }, "filter": { "type": "boolean", "default": true }, "start": { "type": "integer", "minimum": 0, "default": 0 }, "device": { "type": "string", "enum": [ "desktop", "tablet", "mobile" ], "maxLength": 4096, "default": "desktop" }, "async": { "type": "boolean", "default": false, "description": "When false, the API waits for a result and may return an in-progress response that can be polled. When true, the API returns a pollable search response immediately." }, "no_cache": { "type": "boolean", "default": false }, "webhook": { "$ref": "#/components/schemas/WebhookConfig" } } }, "TwitterRequest": { "type": "object", "description": "Parameters for one page of a public Twitter user timeline. Provide exactly one user identifier.", "additionalProperties": false, "oneOf": [ { "required": [ "username" ], "not": { "required": [ "user_id" ] } }, { "required": [ "user_id" ], "not": { "required": [ "username" ] } } ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 51, "pattern": "^@?[A-Za-z0-9_]+$", "description": "Twitter username, with or without a leading `@`." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]+$", "description": "Numeric Twitter user ID." }, "max_results": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of posts to return from this page." }, "cursor": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Opaque `next_cursor` value returned by a previous request." }, "async": { "type": "boolean", "default": false, "description": "When false, the API waits for a result and may return an in-progress response that can be polled. When true, the API returns a pollable search response immediately." }, "webhook": { "$ref": "#/components/schemas/TwitterWebhookConfig" } } }, "WebhookConfig": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "HTTPS webhook URL with a public hostname and no username/password. Localhost, private IPs, special-use IP ranges, and Sukidata system header overrides are rejected. Redirects are not followed." }, "headers": { "type": "object", "description": "Optional custom headers. Header names must be valid HTTP header field names, names are canonicalized, case-insensitive duplicates are rejected, values must not be multiline, and names starting with x-sukidata- are reserved.", "additionalProperties": { "type": "string" } }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "serp.search.queued", "serp.search.processing", "serp.search.completed", "serp.search.failed" ] }, "default": [ "serp.search.completed", "serp.search.failed" ] } } }, "TwitterWebhookConfig": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "HTTPS webhook URL with a public hostname and no username/password. Localhost, private IPs, special-use IP ranges, and Sukidata system header overrides are rejected. Redirects are not followed." }, "headers": { "type": "object", "description": "Optional custom headers. Header names must be valid HTTP header field names, names are canonicalized, case-insensitive duplicates are rejected, values must not be multiline, and names starting with x-sukidata- are reserved.", "additionalProperties": { "type": "string" } }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "twitter.search.queued", "twitter.search.processing", "twitter.search.completed", "twitter.search.failed" ] }, "default": [ "twitter.search.completed", "twitter.search.failed" ] } } }, "WebhookPayload": { "type": "object", "required": [ "id", "object", "type", "api_version", "created_at", "data" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Webhook delivery/event ID. It matches `X-Sukidata-Delivery`." }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "serp.search.queued", "serp.search.processing", "serp.search.completed", "serp.search.failed" ] }, "api_version": { "type": "string", "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/WebhookData" } } }, "WebhookData": { "type": "object", "required": [ "object" ], "additionalProperties": false, "properties": { "object": { "$ref": "#/components/schemas/WebhookSearchObject" } } }, "WebhookSearchObject": { "type": "object", "required": [ "id", "object", "endpoint", "url", "search_metadata", "search_parameters", "usage" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "search" }, "endpoint": { "type": "string", "const": "/v1/serp" }, "url": { "type": "string", "format": "uri", "description": "Authenticated API URL for fetching the search status or result." }, "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" }, "search_information": { "$ref": "#/components/schemas/SERPSearchInformation" }, "organic_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPOrganicResult" } }, "usage": { "$ref": "#/components/schemas/WebhookUsageFields" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "SearchMetadata": { "type": "object", "required": [ "id", "status", "created_at", "total_time_taken" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Success", "Error" ] }, "json_endpoint": { "type": "string", "format": "uri", "description": "File URL for this search's JSON snapshot. Available after the search reaches `Success` or `Error` and remains accessible for one month. The URL does not require API authentication; keep it private." }, "raw_html_file": { "type": "string", "format": "uri", "description": "File URL for this search's HTML snapshot when available. It remains accessible for one month and does not require API authentication; keep it private." }, "google_url": { "type": "string", "format": "uri", "description": "Google Search URL associated with this result." }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the search was created." }, "processed_at": { "type": "string", "format": "date-time", "description": "Time when the search reached a terminal state." }, "total_time_taken": { "type": "number", "minimum": 0, "description": "Elapsed time in seconds, rounded to at most two decimal places. Google's displayed SERP timing, when available, is `search_information.time_taken_displayed`." } } }, "WebhookUsageFields": { "type": "object", "required": [ "cache_hit" ], "additionalProperties": false, "properties": { "cache_hit": { "type": "boolean", "description": "Whether this search qualified for a zero-credit cached response." }, "credits_used": { "type": "integer", "format": "int64", "description": "Credits consumed by this search." } } }, "ErrorDetail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "const": "search_failed" }, "message": { "type": "string", "const": "Search request failed" } } }, "SearchParameters": { "type": "object", "required": [ "engine", "q", "google_domain", "gl", "hl", "device" ], "additionalProperties": false, "properties": { "engine": { "type": "string", "const": "google", "maxLength": 4096 }, "q": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "\\S" }, "location_requested": { "type": "string", "maxLength": 4096, "description": "Original human-readable location requested by the caller when `location` is supplied." }, "location_used": { "type": "string", "maxLength": 4096, "description": "Resolved Google location when `location` is supplied." }, "as_dt": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_epq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_eq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_lq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_nlo": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_nhi": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_oq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_q": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_qdr": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_rq": { "type": [ "string", "null" ], "maxLength": 4096 }, "as_sitesearch": { "type": [ "string", "null" ], "maxLength": 4096 }, "google_domain": { "type": "string", "maxLength": 4096, "pattern": "^google(?:\\.com|\\.[a-z]{2}|\\.(?:com|co)\\.[a-z]{2})$" }, "gl": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[a-z]{2}$" }, "hl": { "type": "string", "minLength": 2, "maxLength": 32, "pattern": "^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$" }, "uule": { "type": [ "string", "null" ], "maxLength": 4096 }, "ludocid": { "type": [ "string", "null" ], "maxLength": 4096 }, "lsig": { "type": [ "string", "null" ], "maxLength": 4096 }, "kgmid": { "type": [ "string", "null" ], "maxLength": 4096 }, "si": { "type": [ "string", "null" ], "maxLength": 4096 }, "ibp": { "type": [ "string", "null" ], "maxLength": 4096 }, "uds": { "type": [ "string", "null" ], "maxLength": 4096 }, "cr": { "type": [ "string", "null" ], "maxLength": 4096 }, "lr": { "type": [ "string", "null" ], "maxLength": 4096 }, "tbs": { "type": [ "string", "null" ], "maxLength": 4096 }, "tbm": { "type": [ "string", "null" ], "maxLength": 4096 }, "safe": { "type": "string", "enum": [ "off", "active" ], "maxLength": 4096 }, "nfpr": { "type": "boolean" }, "filter": { "type": "boolean" }, "start": { "type": "integer", "minimum": 0 }, "device": { "type": "string", "enum": [ "desktop", "tablet", "mobile" ], "maxLength": 4096 } } }, "SERPSearchEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" } } }, "SERPEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/SERPSearchEnvelope" }, { "$ref": "#/components/schemas/SERPCompletedResultEnvelope" }, { "$ref": "#/components/schemas/SERPFailedResultEnvelope" } ] }, "SERPCompletedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "search_information" ], "additionalProperties": true, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" }, "search_information": { "$ref": "#/components/schemas/SERPSearchInformation" }, "organic_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPOrganicResult" } }, "ads": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLinkedResult" } }, "answer_box": { "$ref": "#/components/schemas/SERPAnswerBox" }, "ai_overview": { "$ref": "#/components/schemas/SERPAIOverview" }, "knowledge_graph": { "$ref": "#/components/schemas/SERPKnowledgeGraph" }, "local_results": { "$ref": "#/components/schemas/SERPLocalResults" }, "top_stories": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLinkedResult" } }, "images_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPImageResult" } }, "videos_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLinkedResult" } }, "shopping_results": { "type": "array", "items": { "$ref": "#/components/schemas/SERPShoppingResult" } }, "related_questions": { "type": "array", "description": "People Also Ask and related AI Overview results when available.", "items": { "$ref": "#/components/schemas/SERPRelatedQuestion" } }, "related_searches": { "type": "array", "items": { "$ref": "#/components/schemas/SERPRelatedSearch" } }, "pagination": { "$ref": "#/components/schemas/SERPPagination" } } }, "SERPFailedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "error" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/SearchParameters" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "SERPSearchInformation": { "type": "object", "description": "Search metadata from the Google results page and request.", "required": [ "query_displayed" ], "additionalProperties": true, "properties": { "query_displayed": { "type": "string", "minLength": 1 }, "total_results": { "type": "integer", "minimum": 0 }, "time_taken_displayed": { "type": "number", "minimum": 0, "description": "Time displayed by Google on the SERP, in seconds, when present. This is independent of `search_metadata.total_time_taken`." } } }, "SERPOrganicResult": { "type": "object", "description": "Structured Google organic search result.", "required": [ "position", "title", "link", "snippet" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1, "description": "1-based rank in returned SERP order. Items must be strictly increasing by array order and cannot repeat." }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri", "description": "Final HTTP(S) destination URL." }, "displayed_link": { "type": "string", "description": "Display URL text shown by Google when available; falls back to the result host." }, "source": { "type": "string", "minLength": 1, "description": "Source label shown by Google when available; falls back to the result host." }, "snippet": { "type": "string", "description": "SERP-provided snippet. Empty string is allowed when Google did not provide one." }, "snippet_highlighted_words": { "type": "array", "items": { "type": "string" } }, "favicon": { "type": "string", "description": "Favicon URL when available. It must not be a data URL." }, "date": { "type": "string" }, "sitelinks": { "type": "object", "additionalProperties": true }, "about_this_result": { "type": "object", "additionalProperties": true }, "about_page_link": { "type": "string", "format": "uri" } } }, "SERPLinkedResult": { "type": "object", "description": "Parsed linked rich SERP card, used for ads, top stories, and videos.", "required": [ "position", "title", "link" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "source": { "type": "string" }, "snippet": { "type": "string" }, "date": { "type": "string" } } }, "SERPImageResult": { "type": "object", "required": [ "position", "title" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "thumbnail": { "type": "string", "format": "uri" } } }, "SERPShoppingResult": { "type": "object", "required": [ "position", "title" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "price": { "type": "string" }, "source": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" } } }, "SERPAIOverview": { "type": "object", "description": "Google AI Overview content when available.", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "success", "unavailable", "fetch_failed" ] }, "page_token": { "type": "string", "description": "Google AI Overview page token when present." }, "message": { "type": "string", "description": "Availability message when no overview can be returned." }, "error": { "type": "string", "description": "Failure reason when overview content could not be retrieved." }, "text_blocks": { "type": "array", "items": { "$ref": "#/components/schemas/SERPAIOverviewTextBlock" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SERPAIOverviewReference" } } } }, "SERPAIOverviewTextBlock": { "type": "object", "required": [ "type", "snippet" ], "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "heading", "paragraph", "list_item" ] }, "snippet": { "type": "string", "minLength": 1 } } }, "SERPAIOverviewReference": { "type": "object", "required": [ "index", "title", "link", "source" ], "additionalProperties": true, "properties": { "index": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" }, "source": { "type": "string", "minLength": 1 }, "snippet": { "type": "string" } } }, "SERPRelatedQuestion": { "type": "object", "required": [ "question" ], "additionalProperties": true, "properties": { "question": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "ai_overview", "featured_snippet" ] }, "page_token": { "type": "string" }, "next_page_token": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "displayed_link": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "date": { "type": "string" }, "source_logo": { "type": "string", "format": "uri" } } }, "SERPRelatedSearch": { "type": "object", "required": [ "query" ], "additionalProperties": true, "properties": { "query": { "type": "string", "minLength": 1 }, "link": { "type": "string", "format": "uri" } } }, "SERPLocalResults": { "type": "object", "additionalProperties": true, "properties": { "places": { "type": "array", "items": { "$ref": "#/components/schemas/SERPLocalPlace" } }, "more_locations_link": { "type": "string", "format": "uri" }, "map": { "type": "object", "additionalProperties": true, "properties": { "image": { "type": "string", "format": "uri" }, "link": { "type": "string", "format": "uri" } } } } }, "SERPLocalPlace": { "type": "object", "required": [ "position", "title" ], "additionalProperties": true, "properties": { "position": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1 }, "place_id": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "rating": { "type": "number" }, "reviews": { "type": "integer", "minimum": 0 }, "type": { "type": "string" }, "address": { "type": "string" } } }, "SERPAnswerBox": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "answer": { "type": "string" }, "title": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "displayed_link": { "type": "string" }, "source": { "type": "string" } } }, "SERPKnowledgeGraph": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string" }, "link": { "type": "string", "format": "uri" } } } } }, "SERPPagination": { "type": "object", "additionalProperties": true, "properties": { "next": { "type": "string", "format": "uri" } } }, "TwitterSearchParameters": { "type": "object", "required": [ "engine", "max_results" ], "additionalProperties": false, "oneOf": [ { "required": [ "username" ], "not": { "required": [ "user_id" ] } }, { "required": [ "user_id" ], "not": { "required": [ "username" ] } } ], "properties": { "engine": { "type": "string", "const": "twitter" }, "username": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_]+$" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[0-9]+$" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 8192 } } }, "TwitterSearchEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" } } }, "TwitterEnvelope": { "oneOf": [ { "$ref": "#/components/schemas/TwitterSearchEnvelope" }, { "$ref": "#/components/schemas/TwitterCompletedResultEnvelope" }, { "$ref": "#/components/schemas/TwitterFailedResultEnvelope" } ] }, "TwitterCompletedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "user", "tweets" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" }, "user": { "$ref": "#/components/schemas/TwitterUser" }, "tweets": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Opaque cursor for the next page. Omitted when no next page is available." } } }, "TwitterFailedResultEnvelope": { "type": "object", "required": [ "search_metadata", "search_parameters", "error" ], "additionalProperties": false, "properties": { "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "TwitterUser": { "type": "object", "required": [ "id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "username": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "description": { "type": "string" }, "profile_image_url": { "type": "string", "format": "uri" }, "verified": { "type": "boolean" }, "followers_count": { "type": "integer", "minimum": 0 }, "following_count": { "type": "integer", "minimum": 0 }, "tweet_count": { "type": "integer", "minimum": 0 } } }, "TwitterTweet": { "type": "object", "required": [ "id", "text" ], "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "text": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "Post creation time in UTC, when available." }, "language": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "author": { "$ref": "#/components/schemas/TwitterUser" }, "metrics": { "$ref": "#/components/schemas/TwitterMetrics" }, "conversation_id": { "type": "string" } } }, "TwitterMetrics": { "type": "object", "additionalProperties": false, "properties": { "like_count": { "type": "integer", "minimum": 0 }, "retweet_count": { "type": "integer", "minimum": 0 }, "reply_count": { "type": "integer", "minimum": 0 }, "quote_count": { "type": "integer", "minimum": 0 }, "bookmark_count": { "type": "integer", "minimum": 0 }, "view_count": { "type": "integer", "minimum": 0 } } }, "TwitterWebhookPayload": { "type": "object", "required": [ "id", "object", "type", "api_version", "created_at", "data" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Webhook delivery/event ID. It matches `X-Sukidata-Delivery`." }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "twitter.search.queued", "twitter.search.processing", "twitter.search.completed", "twitter.search.failed" ] }, "api_version": { "type": "string", "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/TwitterWebhookData" } } }, "TwitterWebhookData": { "type": "object", "required": [ "object" ], "additionalProperties": false, "properties": { "object": { "$ref": "#/components/schemas/TwitterWebhookSearchObject" } } }, "TwitterWebhookSearchObject": { "type": "object", "required": [ "id", "object", "endpoint", "url", "search_metadata", "search_parameters", "usage" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "search" }, "endpoint": { "type": "string", "const": "/v1/twitter" }, "url": { "type": "string", "format": "uri", "description": "Authenticated API URL for fetching the search status or result." }, "search_metadata": { "$ref": "#/components/schemas/SearchMetadata" }, "search_parameters": { "$ref": "#/components/schemas/TwitterSearchParameters" }, "user": { "$ref": "#/components/schemas/TwitterUser" }, "tweets": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "next_cursor": { "type": "string", "minLength": 1, "maxLength": 8192 }, "usage": { "$ref": "#/components/schemas/WebhookUsageFields" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "ErrorBody": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 80, "pattern": "^[a-z][a-z0-9_]*$" }, "message": { "type": "string", "minLength": 1, "maxLength": 240 } } } } } }