{ "openapi": "3.1.0", "info": { "title": "Simplo API", "version": "1.0.0" }, "servers": [ { "url": "https://api.getsimplo.ai/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "description": "The projects (one per brand) the key owner has. Most other endpoints need a project id from here.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ], "additionalProperties": {} } } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/brand": { "get": { "operationId": "getBrand", "summary": "Get the brand profile", "description": "The project's brand profile: voice, audience, products, colors, typography.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "A project id from List projects.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected accounts", "description": "The social accounts connected to the project and the platforms that are not. A post only goes out to a connected platform that does not need a reconnect. Accounts are connected in the Simplo app.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "A project id from List projects.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok", "facebook" ] }, "username": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "needsReconnect": { "type": "boolean" }, "connectedAt": { "type": [ "string", "null" ] } }, "required": [ "platform", "needsReconnect" ], "additionalProperties": false } }, "notConnected": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "facebook" ] } } }, "required": [ "connected", "notConnected" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credits": { "get": { "operationId": "getCredits", "summary": "Get the credit balance", "description": "The plan and credits. creditsRemaining is everything that can be spent: the plan's credits, used first, plus bonus credits. planCredits describes the plan's monthly allowance only.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "creditsRemaining": { "type": "number" }, "planCredits": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": "number" }, "remaining": { "type": "number" }, "percentUsed": { "type": "number" }, "resetsAt": { "type": [ "string", "null" ] } }, "required": [ "used", "limit", "remaining", "percentUsed" ], "additionalProperties": false }, "bonusCredits": { "type": "number" }, "plan": { "type": "string" }, "status": { "type": "string" }, "isTrial": { "type": "boolean" }, "trialDaysLeft": { "type": "number" }, "billingInterval": { "type": [ "string", "null" ] }, "billingPeriodEnd": { "type": [ "string", "null" ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "creditsRemaining", "planCredits", "bonusCredits", "plan", "status", "isTrial", "billingInterval", "billingPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts": { "get": { "operationId": "listPosts", "summary": "List posts", "description": "The project's posts (drafts, scheduled, published, failed, missed), newest first. A draft_scheduled post is a draft placed on its day: it never sends by itself.", "parameters": [ { "name": "projectId", "in": "query", "required": true, "description": "The project whose posts to list.", "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "Only posts of this month, as YYYY-MM.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "draft_scheduled", "scheduled", "published", "partially_published", "failed", "missed" ] }, "caption": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "scheduledAt": { "type": "string" }, "publishedAt": { "type": "string" }, "imageUrl": { "type": "string" }, "postType": { "type": "string", "enum": [ "single", "carousel", "video" ] }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ], "additionalProperties": false }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "imageUrl": { "type": "string" }, "order": { "type": "number" }, "caption": { "type": "string" } }, "required": [ "id", "imageUrl", "order" ], "additionalProperties": {} } }, "error": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "caption", "platforms", "createdAt" ], "additionalProperties": {} } } } } }, "400": { "description": "The request is not valid. Error code: validation_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPost", "summary": "Create a post", "description": "Saves a single-image or video post as a draft (the default) or scheduled. A draft with scheduledAt is placed on that day in the plan (draft_scheduled) and never sends by itself. A scheduled post is published automatically at scheduledAt, which must be in the future and on the hour. A video post takes videoUrl (a public MP4 or MOV link, up to 100 MB) or an already uploaded video; its first frame is the cover. Not for X. Pass at most one of imageUrl, video and videoUrl.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 255 characters. Repeating a request with the same key within 24 hours returns the first answer instead of doing the work again.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project that owns the post." }, "caption": { "type": "string", "description": "The post text." }, "imageUrl": { "description": "A public picture URL. Mutually exclusive with video and videoUrl.", "type": "string", "format": "uri" }, "video": { "description": "A video already uploaded with Upload a video. Mutually exclusive with imageUrl and videoUrl.", "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ] }, "videoUrl": { "description": "A public MP4 or MOV link for Simplo to fetch. Mutually exclusive with imageUrl and video.", "type": "string", "format": "uri" }, "platforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "facebook" ] }, "description": "Where the post goes. X is not supported." }, "status": { "default": "draft", "description": "draft saves it; scheduled publishes it at scheduledAt.", "type": "string", "enum": [ "draft", "scheduled" ] }, "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 with UTC offset. Scheduling needs a future whole hour; a draft's date isn't checked until it is scheduled." } }, "required": [ "projectId", "caption", "platforms" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "draft_scheduled", "scheduled", "published", "partially_published", "failed", "missed" ] }, "caption": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "scheduledAt": { "type": "string" }, "publishedAt": { "type": "string" }, "imageUrl": { "type": "string" }, "postType": { "type": "string", "enum": [ "single", "carousel", "video" ] }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ], "additionalProperties": false }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "imageUrl": { "type": "string" }, "order": { "type": "number" }, "caption": { "type": "string" } }, "required": [ "id", "imageUrl", "order" ], "additionalProperties": {} } }, "error": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "caption", "platforms", "createdAt" ], "additionalProperties": {} } } } }, "400": { "description": "The request is not valid. Error code: validation_error, invalid_schedule_time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. Error code: idempotency_in_progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large. Error code: video_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request. Error code: idempotency_key_reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get a post", "description": "One post, with its status and any publish error.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "draft_scheduled", "scheduled", "published", "partially_published", "failed", "missed" ] }, "caption": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "scheduledAt": { "type": "string" }, "publishedAt": { "type": "string" }, "imageUrl": { "type": "string" }, "postType": { "type": "string", "enum": [ "single", "carousel", "video" ] }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ], "additionalProperties": false }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "imageUrl": { "type": "string" }, "order": { "type": "number" }, "caption": { "type": "string" } }, "required": [ "id", "imageUrl", "order" ], "additionalProperties": {} } }, "error": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "caption", "platforms", "createdAt" ], "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updatePost", "summary": "Edit a post", "description": "Changes a post's caption, picture, video or platforms; send only what changes. scheduledAt places a draft on a day without scheduling it; a scheduled post's time is changed with the schedule endpoint. Editing a scheduled post changes what goes out at its time. A post that has gone out, or is going out now, cannot be edited. Send at least one field, and at most one of imageUrl, video and videoUrl.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "caption": { "description": "The new post text.", "type": "string" }, "imageUrl": { "description": "A public picture URL. Mutually exclusive with video and videoUrl.", "type": "string", "format": "uri" }, "video": { "description": "A video already uploaded with Upload a video. Mutually exclusive with imageUrl and videoUrl.", "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ] }, "videoUrl": { "description": "A public MP4 or MOV link for Simplo to fetch. Mutually exclusive with imageUrl and video.", "type": "string", "format": "uri" }, "platforms": { "description": "The new list of platforms.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "facebook" ] } }, "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 with UTC offset. Scheduling needs a future whole hour; a draft's date isn't checked until it is scheduled." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "draft_scheduled", "scheduled", "published", "partially_published", "failed", "missed" ] }, "caption": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "scheduledAt": { "type": "string" }, "publishedAt": { "type": "string" }, "imageUrl": { "type": "string" }, "postType": { "type": "string", "enum": [ "single", "carousel", "video" ] }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ], "additionalProperties": false }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "imageUrl": { "type": "string" }, "order": { "type": "number" }, "caption": { "type": "string" } }, "required": [ "id", "imageUrl", "order" ], "additionalProperties": {} } }, "error": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "caption", "platforms", "createdAt" ], "additionalProperties": {} } } } }, "400": { "description": "The request is not valid. Error code: validation_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. Error code: already_published, publishing_in_progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large. Error code: video_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deletePost", "summary": "Delete a post", "description": "Deletes a post from Simplo; this cannot be undone. A published post stays on the social platforms: only Simplo's record and its analytics go. Deleting a scheduled post stops it from going out.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/generate/captions": { "post": { "operationId": "generateCaptions", "summary": "Generate caption ideas", "description": "On-brand post ideas (hook, caption, hashtags, image prompt) for a topic, saved as a research session. Costs credits. Needs a completed brand profile.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project whose brand the ideas follow." }, "topic": { "type": "string", "minLength": 1, "description": "What the posts are about." }, "platforms": { "description": "Shape the ideas for these platforms.", "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "facebook" ] } }, "limit": { "description": "How many ideas, 1 to 10.", "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "projectId", "topic" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string" }, "ideas": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } } }, "required": [ "ideas" ], "additionalProperties": false } } } }, "400": { "description": "The request is not valid. Error code: validation_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Error code: insufficient_credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-costs-credits": true } }, "/generate/image": { "post": { "operationId": "generateImage", "summary": "Generate images", "description": "On-brand images for a post, saved to the project's image history. Costs credits (more for more images). Style \"ad-layout\" sets real type over a photo; other styles draw text badly. Every model tier currently runs as \"standard\".", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project whose brand the images follow." }, "prompt": { "type": "string", "minLength": 1, "description": "What the image shows." }, "format": { "default": "instagram-post", "type": "string", "enum": [ "instagram-post", "instagram-story", "instagram-portrait", "tiktok", "x-post", "facebook-post", "facebook-cover" ] }, "style": { "default": "studio", "type": "string", "enum": [ "ad-layout", "studio", "candid", "cinematic", "retro-film", "flat-illustration", "hand-drawn", "render-3d", "bold-type", "minimal" ] }, "adBackground": { "default": "image", "type": "string", "enum": [ "image", "brand" ] }, "modelTier": { "default": "standard", "type": "string", "enum": [ "fast", "standard", "premium" ] }, "imageCount": { "default": 1, "description": "How many images, 1 to 4. Each one costs credits.", "type": "integer", "minimum": 1, "maximum": 4 }, "includeLogo": { "default": false, "type": "boolean" } }, "required": [ "projectId", "prompt" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "generationId": { "type": "string" }, "style": { "type": "string" }, "format": { "type": "string" }, "imageUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "generationId", "style", "format", "imageUrls" ], "additionalProperties": false } } } }, "400": { "description": "The request is not valid. Error code: validation_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Error code: insufficient_credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-costs-credits": true } }, "/generate/carousel": { "post": { "operationId": "generateCarousel", "summary": "Generate a carousel", "description": "Writes and draws an Instagram carousel about a topic and saves it as a draft post. Costs credits: the slide copy, plus each picture when pictures are on. It is never published or scheduled here. A slide in overflowSlides has more text than fits. If saving the draft fails after the slides were drawn, the answer is 502 with the slide URLs in details.slides: those slides are paid for, so use the URLs rather than retrying (a retry with the same Idempotency-Key gets the same answer).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 255 characters. Repeating a request with the same key within 24 hours returns the first answer instead of doing the work again.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "description": "The project that owns the carousel." }, "topic": { "type": "string", "minLength": 1, "description": "What the carousel is about." }, "slideCount": { "default": 5, "description": "How many slides, 2 to 10.", "type": "integer", "minimum": 2, "maximum": 10 }, "style": { "type": "string", "enum": [ "editorial", "clean", "boldPhoto", "dark" ] }, "pictures": { "default": false, "description": "Draw a picture on each slide. Costs extra credits.", "type": "boolean" }, "caption": { "description": "The post text; written for you when left out.", "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 with UTC offset. Scheduling needs a future whole hour; a draft's date isn't checked until it is scheduled." } }, "required": [ "projectId", "topic" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "draft_scheduled", "scheduled", "published", "partially_published", "failed", "missed" ] }, "caption": { "type": "string" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "number" }, "imageUrl": { "type": "string" }, "text": { "type": "string" } }, "required": [ "number", "imageUrl" ], "additionalProperties": false } }, "overflowSlides": { "type": "array", "items": { "type": "number" } }, "creditsRefunded": { "type": "number" } }, "required": [ "postId", "status", "caption", "slides" ], "additionalProperties": false } } } }, "400": { "description": "The request is not valid. Error code: validation_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough credits. Error code: insufficient_credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. Error code: idempotency_in_progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request. Error code: idempotency_key_reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-costs-credits": true } }, "/posts/{id}/schedule": { "post": { "operationId": "schedulePost", "summary": "Schedule a post", "description": "Schedules a post, or moves a scheduled one to a new time. It is published to the connected accounts automatically at scheduledAt, which must be in the future and on the hour; without it the post keeps the time it has. Works on drafts, scheduled, missed and failed posts. A post that already went out cannot be rescheduled. Refused for a post that includes X.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 with UTC offset. Scheduling needs a future whole hour; a draft's date isn't checked until it is scheduled." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "draft_scheduled", "scheduled", "published", "partially_published", "failed", "missed" ] }, "caption": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "scheduledAt": { "type": "string" }, "publishedAt": { "type": "string" }, "imageUrl": { "type": "string" }, "postType": { "type": "string", "enum": [ "single", "carousel", "video" ] }, "video": { "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ], "additionalProperties": false }, "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "imageUrl": { "type": "string" }, "order": { "type": "number" }, "caption": { "type": "string" } }, "required": [ "id", "imageUrl", "order" ], "additionalProperties": {} } }, "error": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "caption", "platforms", "createdAt" ], "additionalProperties": {} } } } }, "400": { "description": "The request is not valid. Error code: validation_error, invalid_schedule_time, platform_not_available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. Error code: already_published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}/publish": { "post": { "operationId": "publishPost", "summary": "Publish a post now", "description": "Publishes the post to its platforms immediately, on the real accounts; this cannot be undone. Safe to retry: a platform already published is skipped. The answer lists a result per platform and allSuccess. A send that is still in progress (a video, or a post going through a posting partner) answers 202 with pending: true; read the post for the result. A post that is already live answers 200 with alreadyPublished: true. Refused for a post that includes X.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 255 characters. Repeating a request with the same key within 24 hours returns the first answer instead of doing the work again.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "platform", "success" ], "additionalProperties": {} } }, "allSuccess": { "type": "boolean" }, "pending": { "type": "boolean" }, "alreadyPublished": { "type": "boolean" } }, "additionalProperties": {} } } } }, "202": { "description": "Accepted. The send is still in progress (pending: true); read the post for the result", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "boolean", "const": true }, "allSuccess": { "type": "boolean" } }, "required": [ "pending" ], "additionalProperties": {} } } } }, "400": { "description": "The request is not valid. Error code: validation_error, platform_not_available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. Error code: publishing_in_progress, idempotency_in_progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request. Error code: idempotency_key_reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/videos": { "post": { "operationId": "uploadVideo", "summary": "Upload or import a video", "description": "Hosts a video for a video post. Send an MP4 or MOV (up to 100 MB) as multipart/form-data in the file field, with projectId in the query string, or send JSON with a public url for Simplo to fetch, with projectId in the body or the query. The upload is streamed, never held in memory. Pass the returned video to Create a post as video.", "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "The project that owns the video. Required for an upload.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "description": "Required here or in the query string.", "type": "string" }, "url": { "type": "string", "format": "uri", "description": "A public MP4 or MOV link for Simplo to fetch." } }, "required": [ "url" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "MP4 or MOV, up to 100 MB" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "type": "object", "properties": { "url": { "type": "string" }, "coverUrl": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" } }, "required": [ "url", "coverUrl", "durationSeconds", "width", "height", "bytes" ], "additionalProperties": false } }, "required": [ "video" ], "additionalProperties": false } } } }, "400": { "description": "The request is not valid. Error code: validation_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key. Error code: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed. Error code: subscription_inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Error code: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large. Error code: video_too_large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests. Error code: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A platform or AI provider failed. Error code: upstream_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "Get the OpenAPI document", "description": "This API described as an OpenAPI 3.1 document. No API key needed.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "500": { "description": "Something went wrong on our side. Error code: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "smp_live_… key from Settings → API keys" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "forbidden", "not_found", "validation_error", "invalid_schedule_time", "platform_not_available", "already_published", "publishing_in_progress", "conflict", "idempotency_key_reused", "idempotency_in_progress", "insufficient_credits", "subscription_inactive", "video_too_large", "rate_limited", "upstream_error", "internal_error" ], "description": "A stable machine-readable code, e.g. validation_error." }, "message": { "type": "string", "description": "A human-readable explanation." }, "details": { "description": "Extra context, such as the failing fields of a validation_error." } } } } } } } }