{ "openapi": "3.1.0", "info": { "title": "Octoque API", "version": "0.1.0", "description": "Schedule one video or post to Instagram, TikTok, YouTube, LinkedIn, X, Facebook and Threads. Authenticate with an API key (Authorization: Bearer oq_live_...). Guide: https://octoque.com/docs/api" }, "servers": [ { "url": "https://api.octoque.com" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Accounts" }, { "name": "Media" }, { "name": "Posts" }, { "name": "Scheduling" }, { "name": "Results" }, { "name": "Meta" } ], "paths": { "/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List connected accounts", "operationId": "list_accounts_v1_accounts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" } }, "/v1/accounts/{account_id}/tiktok": { "get": { "tags": [ "Accounts" ], "summary": "Read a TikTok creator's posting options", "description": "Needs the `post.write` scope.", "operationId": "tiktok_creator_v1_accounts__account_id__tiktok_get", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "media", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(video|image)$", "default": "video", "title": "Media" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-octoque-scope": "post.write" } }, "/v1/accounts/{account_id}": { "patch": { "tags": [ "Accounts" ], "summary": "Set an account's audience regions", "operationId": "set_audience_v1_accounts__account_id__patch", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write" } }, "/v1/media": { "post": { "tags": [ "Media" ], "summary": "Upload a video or photo", "operationId": "upload_v1_media_post", "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "MP4 or MOV video, or JPG, PNG or WebP photo. Up to 1 GB." } } } } } } }, "get": { "tags": [ "Media" ], "summary": "List uploaded files", "operationId": "list_media_v1_media_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" } }, "/v1/media/{media_id}": { "get": { "tags": [ "Media" ], "summary": "Get a file", "description": "Needs the `post.read` scope.", "operationId": "get_media_v1_media__media_id__get", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Media Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-octoque-scope": "post.read" }, "delete": { "tags": [ "Media" ], "summary": "Delete a file", "operationId": "delete_media_v1_media__media_id__delete", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Media Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write" } }, "/v1/posts": { "post": { "tags": [ "Posts" ], "summary": "Create a post (draft)", "operationId": "create_post_v1_posts_post", "parameters": [ { "name": "idempotency-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write" }, "get": { "tags": [ "Posts" ], "summary": "List posts", "operationId": "list_posts_v1_posts_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "To" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" } }, "/v1/posts/{post_id}": { "get": { "tags": [ "Posts" ], "summary": "Get a post", "operationId": "get_post_v1_posts__post_id__get", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" }, "patch": { "tags": [ "Posts" ], "summary": "Edit a post", "operationId": "edit_post_v1_posts__post_id__patch", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write" }, "delete": { "tags": [ "Posts" ], "summary": "Delete a post", "operationId": "delete_post_v1_posts__post_id__delete", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write" } }, "/v1/posts/{post_id}/schedule": { "post": { "tags": [ "Posts" ], "summary": "Schedule a post", "operationId": "schedule_v1_posts__post_id__schedule_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScheduleIn" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/posts/{post_id}/queue": { "post": { "tags": [ "Posts" ], "summary": "Add a post to the queue", "operationId": "add_to_queue_v1_posts__post_id__queue_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/posts/{post_id}/publish-now": { "post": { "tags": [ "Posts" ], "summary": "Post now", "operationId": "publish_now_v1_posts__post_id__publish_now_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/posts/{post_id}/cancel": { "post": { "tags": [ "Posts" ], "summary": "Unschedule a post", "operationId": "cancel_v1_posts__post_id__cancel_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/posts/{post_id}/retry": { "post": { "tags": [ "Posts" ], "summary": "Retry failed platforms", "operationId": "retry_v1_posts__post_id__retry_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/posts/{post_id}/targets/{target_id}/unpublish": { "post": { "tags": [ "Posts" ], "summary": "Delete a live post on its platform", "description": "Needs the `post.delete_published` scope.", "operationId": "unpublish_v1_posts__post_id__targets__target_id__unpublish_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Target Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-octoque-scope": "post.delete_published" } }, "/v1/posts/{post_id}/duplicate": { "post": { "tags": [ "Posts" ], "summary": "Duplicate a post", "operationId": "duplicate_v1_posts__post_id__duplicate_post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.write` scope.", "x-octoque-scope": "post.write" } }, "/v1/posts/{post_id}/history": { "get": { "tags": [ "Posts" ], "summary": "A post's history", "operationId": "history_v1_posts__post_id__history_get", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" } }, "/v1/golden-hour": { "get": { "tags": [ "Scheduling" ], "summary": "Next golden hour per platform", "operationId": "golden_hour_v1_golden_hour_get", "parameters": [ { "name": "platforms", "in": "query", "required": false, "schema": { "type": "string", "default": "instagram,tiktok,youtube,linkedin,x", "title": "Platforms" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Any valid API key." } }, "/v1/queue-slots": { "get": { "tags": [ "Scheduling" ], "summary": "List queue times", "operationId": "list_slots_v1_queue_slots_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" }, "post": { "tags": [ "Scheduling" ], "summary": "Add a queue time", "operationId": "add_slot_v1_queue_slots_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlotIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/queue-slots/{slot_id}": { "delete": { "tags": [ "Scheduling" ], "summary": "Remove a queue time", "operationId": "remove_slot_v1_queue_slots__slot_id__delete", "parameters": [ { "name": "slot_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Slot Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.publish` scope.", "x-octoque-scope": "post.publish" } }, "/v1/posts/{post_id}/metrics": { "get": { "tags": [ "Results" ], "summary": "A post's results", "operationId": "post_metrics_v1_posts__post_id__metrics_get", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Post Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Needs the `post.read` scope.", "x-octoque-scope": "post.read" } }, "/v1/analytics/summary": { "get": { "tags": [ "Results" ], "summary": "Results summary", "description": "Needs the `post.read` scope.", "operationId": "summary_v1_analytics_summary_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 7, "default": 28, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-octoque-scope": "post.read" } }, "/v1/health": { "get": { "tags": [ "Meta" ], "summary": "Health check", "operationId": "health_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "description": "No key needed.", "security": [] } } }, "components": { "schemas": { "AudienceIn": { "properties": { "audience_regions": { "items": { "type": "string" }, "type": "array", "title": "Audience Regions" } }, "type": "object", "required": [ "audience_regions" ], "title": "AudienceIn" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "PostIn": { "properties": { "caption": { "type": "string", "title": "Caption", "default": "" }, "media_ids": { "items": { "type": "string" }, "type": "array", "title": "Media Ids" }, "targets": { "items": { "$ref": "#/components/schemas/TargetIn" }, "type": "array", "minItems": 1, "title": "Targets" } }, "type": "object", "required": [ "targets" ], "title": "PostIn" }, "PostPatch": { "properties": { "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caption" }, "targets": { "items": { "$ref": "#/components/schemas/TargetPatch" }, "type": "array", "title": "Targets" }, "add": { "items": { "$ref": "#/components/schemas/TargetIn" }, "type": "array", "maxItems": 20, "title": "Add" }, "remove": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "title": "Remove" } }, "type": "object", "title": "PostPatch" }, "ScheduleIn": { "properties": { "at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "At" } }, "type": "object", "title": "ScheduleIn" }, "SlotIn": { "properties": { "weekdays": { "items": { "type": "integer" }, "type": "array", "minItems": 1, "title": "Weekdays" }, "time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "title": "Time" }, "label": { "type": "string", "title": "Label", "default": "" } }, "type": "object", "required": [ "weekdays", "time" ], "title": "SlotIn" }, "TargetIn": { "properties": { "account_id": { "type": "string", "title": "Account Id" }, "caption_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caption Override" }, "options": { "additionalProperties": true, "type": "object", "title": "Options" }, "scheduled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Scheduled At" } }, "type": "object", "required": [ "account_id" ], "title": "TargetIn" }, "TargetPatch": { "properties": { "id": { "type": "string", "title": "Id" }, "caption_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Caption Override" }, "options": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Options" }, "scheduled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Scheduled At" } }, "type": "object", "required": [ "id" ], "title": "TargetPatch" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An Octoque API key, made in the app under You → Developers & AI." } } } }